Workflow

This page describes how we develop aare.

GitHub centric

We use GitHub for all development. Issues and pull requests provide a platform for collaboration as well as a record of the development process. Even if we discuss things in person, we record the outcome in an issue. If a particular implementation is chosen over another, the reason should be recorded in the pull request.

Branches

We aim for an as lightweight branching strategy as possible. Short-lived feature branches are merged back into main. The main branch is expected to always be in a releasable state. A release is simply a tag on main which provides a reference and triggers the CI to build the release artifacts (conda, pypi etc.). For large features consider merging smaller chunks into main as they are completed, rather than waiting for the entire feature to be finished. Worst case make sure your feature branch merges with main regularly to avoid large merge conflicts later on.

Note

The main branch is expected to always work. Feel free to pull from main instead of sticking to a release

Releases

Release early, release often. As soon as “enough” new features have been implemented, a release is created. A release should not be a big thing, rather a routine part of development that does not require any special person or unfamiliar steps.

Checklists for deployment

Feature:

  1. Create a new issue for the feature (label feature)

  2. Create a new branch from main.

  3. Implement the feature including test and documentation

  4. Add the feature to RELEASE.md under head

  5. Create a pull request linked to the issue

  6. Code is reviewed by at least one other person

  7. Once approved, the branch is merged into main

BugFix:

Essentially the same as for a feature, if possible start with a failing test that demonstrates the bug.

  1. Create a new issue for the bug (label bug)

  2. Create a new branch from main.

  3. Write a test that fails for the bug

  4. Implement the fix

  5. Run the test to ensure it passes

  6. Add the bugfix to RELEASE.md under head

  7. Create a pull request linked to the issue.

  8. Code is reviewed by at least one other person

  9. Once approved, the branch is merged into main

Release:

  1. Once “enough” new features have been implemented, a release is created

  2. Update RELEASE.md with the tag of the release and verify that it is complete

  3. Create the release in GitHub describing the new features and bug fixes

  4. CI makes magic

Update documentation only:

Attention

It’s possible to update the documentation without changing the code, but take care since the docs will reflect the code in main and not the latest release.

  1. Create a PR to main with the documentation changes

  2. Create a pull request linked to the issue.

  3. Code is reviewed by at least one other person

  4. Once merged you can manually trigger the CI workflow for documentation