Branching and Workflow#

Our branching strategy#

While you can use any type of branching strategy and naming as you work in your personal fork, we have three branches in the tobac repository:

  • RC_*

  • dev_*

  • hotfix

RC_* is the release candidate of the next tobac version. The asterisk stands here for the specific tobac version: RC_vx.x.x (e.g. RC_v1.5.0). Pull requests to this branch need one review to be accepted before it can be merged into main. The PR author is ultimately responsible for how many reviews they require, and they or the 1st reviewer may also request a second review by tagging reviewers in the comment on the PR on Github. If an assigned reviewer does not respond on GitHub, contact the assigned person via email.

dev_* is the development branch where we experiment with new features. This branch is perfectly suited to collaboratively work on a feature together with other tobac developers (see Mentoring and Collaboration). In general, this branch is used for long-term, comprehensive code changes that might not be covered by a single pull request and where it might not be conceivable in which future tobac version to include the changes. There are no branch protection rules for this branch, which means that collaborators of our GitHub organization can directly push changes to this branch. Note that dev_ can never directly merged into main, it has be merged into the release candidate branch RC_* first! There can be more than one dev_* branch, therefore it we recommend to describe the feature to work on in the respective branch (e.g. dev_xarray_transition).

hotfix is the branch we use for hotfixes, i.e. bug fixes that need to be released as fast as possible because it influences people’s code. This branch needs only one review before it can directly merged into main.

In brief: Unless you are collaboratively working on a comprehensive feature or on a hotfix, the branch to submit your pull request to is the next release candidate RC_v.x.x.x

GitHub workflow#

We use several GitHub actions to assure continuous integration and to enable an efficient code development and release process. Our workflow configuration can be found in .github/workflows and encompass

  • check that code is formatted using the latest stable version of black

  • linting of the latest code changes that checks the code quality and results in a score compared to the most recent released version

  • check of the zenodo JSON file that ensures that the citation is correct

  • check that all unit tests pass (including testing on multiple operating systems) and report test coverage

  • check that the example jupyter notebooks run without problems

Releasing a new version#

This is the checklist of steps for a release of a new tobac version:

  • Bump version in __init__.py in RC_vXXX

  • Add changelog in RC_vXXX

  • Regenerate example notebooks with the new version

  • Merge RC_vXXX into main

  • Merge updated main branch back into release and dev branches

  • Delete RC_vXXX branch

  • Create release

  • Push release to conda-forge: tobac-project/tobac-notes

  • Create new tag

  • E-mail tobac mailing list