DBCA OIM developer guidance

This is a resource for OIM developers new to DBCA, to get to a basic standard of understanding of our development tools and processes. Individuals should feel free to skip elements for which they already have a good level of competency. This page is not prescriptive, but it represents a sensible order of operations for a new hire to go through.

Additional resource documentation pages include the following:

Web development stack

To summarise the recommended technology stack for new web development projects:

Python

Python is a general purpose programming language which is dynamically typed, interpreted, and known for its easy readability. General principles to be aware of when undertaking development of applications using Python:

For installation, most *nix operating systems come with a version of Python installed which will probably be sufficient for learning. For usage instructions, see this page. For installation on Windows, see this page.

A suggested syllabus for learning Python for the purposes of web application development is as follows:

Python environment management

Once you start working on more than one project, managing separate and isolated Python environments for each one becomes a requirement. This topic is slightly “extra credit” (it’s most important to get in and start learning the syntax), but it’s worth learning sooner rather than later. This is a good primer on Python virtual environments and why you need them.

There are many different Python environment management tools on the market (pip, pip-tools, Poetry, Pipenv, etc.) and the choice always remain with individual developer, but the current recommended tool is uv. It’s (very) fast, easy to use, and is standards-compliant. First steps are as follows:

Django

Django is our current tool of choice for non-trivial web applications requiring a significant amount of business logic, direct manipulation of databases, and a large amount of user interaction. It is a “full stack” web framework that includes all of the components required to develop a complex web application for internal or external customers. It also boasts some of the best online documentation to be found.

A learning syllabus for Django is as follows:

Examples of DBCA-built web applications using Django:

To minimise development effort, we typically take the following approach when building a new system:

  1. Define a good data model with constraints: Django models.
  2. Add validation for model fields.
  3. Use the built-in Django admin for testing and validation of the data model.

Software development environment

OIM application developers are encouraged to undertake development locally in an environment that is as close as possible to the final deployed application environment in order to reduce the incidence of “works on my machine” problems.

Development tools

Linux

For the best development experience, OIM recommends developers install a variant of Linux on their workstation, either outright or in a dual-boot arrangement with Windows. We’ve found modern Ubuntu to have a good user experience plus up-to-date packages, but the choice of distribution can be entirely up to user preference.

Some good additional resources from the internet are as follows:

Windows

Microsoft has made it surprisingly easy to run a Linux environment under Windows 10 and newer. Windows Subsystem for Linux is a good alternative to a full VM, and is a lot more pleasant for Python development than using the Win32 ported equivalent of the tools. There are a few cases where support is less than optimal (e.g. some complex filesystem interactions fail, meaning you can’t run PostgreSQL natively), but for basic development it provides a good alternative or transitional step to a full UNIX environment.

A decent guide for installing Docker inside the Ubuntu WSL is here (includes instructions for installing the Azure CLI and dotnet core).

Failing that, there’s the option of using an emulator like VirtualBox to run a local Linux VM for development purposes but this can consume a fair amount of your computer’s resources.

Mac OS X

Apple includes a lot of UNIXy tools in the standard OS X environment, but isn’t very prompt in keeping the software up to date. You may have some luck using Homebrew, which is styled to be like a Linux package manager. See https://hackercodex.com/guide/mac-development-configuration/

Software development best practices

The following ebook is a well-regarded and very readable collection of advice related to software development: Andrew Hunt, David Thomas - The Pragmatic Programmer - your journey to mastery

Git

Git is a free and open source version control system. Learning to use Git is non-trivial and can be intimidating. However, it is the most widely-used VCS in the world therefore learning to use it will be a good investment of time for any developer.

All public DBCA source code repositories are located at the department’s GitHub organisation. Usage of the department’s GitHub organisation is subject to the following principles:

GitHub provides this list of introductory resources for getting started with Git.

Here is a very basic workflow of a Git repository and a developer’s fork of it:

  1. Create a fork of a repository (repo) on Github.
  2. Clone the forked repo to your local machine (your fork on Github becomes the “origin”).
  3. Make changes to your local repository and commit the changes.
  4. Push your commits to your remote repository (the fork) on Github.
  5. Open a pull request (PR) from your fork to the original repo (propose changes).
  6. The project owner reviews and merged your PR into the original repo.

Obviously things become progressively more complicated as we add things such as branching, multiple developers collaborating to update a repo, etc. The specific workflow in use should be settled on in each team; consistency of usage within a team is more important than the workflow chosen. A good, basic workflow is the the Github Flow: https://docs.github.com/en/get-started/quickstart/github-flow

A helpful graphic demonstrating the Git commands to move a repository state between locations is as follows:

image

Below are some additional resources to assist with learning Git:

Working on a repository

The high-level expectations for source code management are explained in the ASD guidelines for Software Development. For most multi-contributor projects we use GitHub pull requests as the workflow for contributions/code review.

We recommend the following steps for getting started with a code repository:

git clone https://github.com/your_username/project_name.git
cd project_name

git remote add upstream https://github.com/dbca-wa/project_name.git

Do all of your work on the fork, make a bunch of commits, push frequently, etc. Once a feature is done, use the GitHub UI to create a pull request from your fork to the upstream repository, so that it may be code reviewed. Developers might wish to work on specific features or fixes in a branch and then merge that branch to the main branch as needed, however the specific workflow can be defined by the project owner.

Docker

All modern web applications in the department are built as Docker images and deployed using Kubernetes. This is a whole technical speciality on its own, so we suggest that new developers not already familiar with Docker ease into it over time (concentrate initially on Python, Django and getting set up with collaboration tools).

For the enthusiastic, there are some resources to start learning about Docker below.

Security awareness