Contributing to OpenAustralia Foundation projects

Thank you for helping build tools that give people the information and access they need to take part in Australian democracy. This guide explains how we work with Git and GitHub across our repositories so that contributions are consistent, easy to follow, and clearly licensed.

This file lives in the openaustralia/.github repository and applies to every OpenAustralia Foundation repository unless a repository provides its own CONTRIBUTING.md that overrides it. Some projects have their own workflow for good reasons (for example, Right to Know), so always check for a repository-specific file first.

Status: This is our shared starting point, agreed by the team in July 2026. A few details are still being finalised and are marked as open questions at the end. Suggestions are welcome via an issue or pull request.

We use GitHub Flow. The key principle is simple:

The main branch is always production-ready.

In practice that means:

1. Create a branch off main for your work.
2. Open a pull request early. Pull requests are how the team keeps up with what is changing. They are for visibility and shared understanding, not just a gate to pass through.
3. Open your pull request as a draft while it is still in progress.
4. Make sure all the checks in .github/workflows pass before you take the pull request out of draft. The author is responsible for confirming the tests are green.
5. Once reviewed and passing, the pull request is merged. The author normally does the merging.
6. Deploy from main.

GitHub Flow does not prescribe how staging works, and our practice varies by project. Where staging is used, staging branches (for example staging or staging1) are treated as ephemeral: they are created for a specific server or group of changes and reset as needed. Follow the conventions in the repository you are working in, and prefer aiming pull requests at main.

Name branches using the Conventional Branch convention, with a type prefix followed by the issue number and a short description, for example:

• feature/123-add-postcode-search
• bugfix/890-fix-pagination
• hotfix/123-correct-broken-link
• chore/21-update-dependencies
• doc/7391-clarify-setup-steps

Assign pull requests you create to yourself so it is clear who is driving each change.

• Fill in the pull request template. Describe what you changed, why, and how you tested it.
• Keep changes focused and reviewable.
• Link to any related issue.
• Take the pull request out of draft only once the checks pass.

We are moving towards requiring a sign-off trailer on every commit so that we have a clear, documented record that each contribution can be lawfully included in our projects. This matters more than ever now that AI tools are commonly involved in writing code.

Sign off your commits using the Developer Certificate of Origin (DCO). Add a Signed-off-by line by committing with the -s flag:

git commit -s -m "Your commit message"

By signing off, you certify that you wrote the change or otherwise have the right to submit it under our licence.

As well as the sign off by the primary author/s at the bottom of the commit, list any other contributors using "Co-authored-by: Contributor Name email@example.com" immediately following the sign off line/s.

We welcome contributions that use AI tools, provided you take responsibility for what you submit. If you use an AI tool to generate a meaningful part of a contribution:

• Disclose it, in two places: an Assisted-by trailer on each commit the tool helped produce, and a short note in the pull request description. Both name the tool and the specific model, in the same form:

  Assisted-by: Claude Code:claude-opus-5
  

  The commit trailer belongs in the trailer block at the end of the message, alongside Signed-off-by. Report the model you actually used. Minor use, such as autocomplete or grammar checking, does not need disclosing.

• Review it. You are responsible for reviewing all AI-generated material before submitting, to the same standard as any other contribution. Be prepared to explain and support the change.

• Cite sources where you can. If an AI tool adapted code or an approach from an identifiable source, note the reference and its licence so reviewers can check for licence compatibility and any gotchas.

A human, not an AI agent, must sign off the commit, as this is a commitment only a person can make.

Reviews help us share knowledge and keep main healthy. Repositories use a CODEOWNERS file to request reviews from the right people. A review is about understanding and improving the change together, not gatekeeping.

These points were raised but not yet settled. We will update this guide once the team decides:

• Branch prefix wording: whether to standardise on full words (feature/, bugfix/) or short forms (feat/). This guide currently uses the full-word forms from Conventional Branch.
• Cryptographic signing: whether to require GPG-signed commits in addition to the DCO sign-off.
• Staging conventions: whether to define a single org-wide approach to staging environments and branches.
• Contributor Licence Agreement: we removed the CLA requirement for now. Whether to reinstate one, and in what form, is still open.

OpenAustralia Foundation - https://www.oaf.org.au