Git branches¶

PISM development loosely follows the Git branching model described in A successful Git branching model by Vincent Driessen.1

PISM’s repository contains two long-lived branches: main and dev.

The default branch main contains released code. This way users can clone https://github.com/pism/pism and get the latest PISM release.

The dev branch contains code that is ready to be included in the next release.

Current development is done in topic branches started from dev. Once a new feature or improvement is finished, tested, and documented, the topic branch is merged into dev and deleted. Each topic branch should contain changes related to one particular topic.2

If one person is responsible for working on a topic branch it works well to keep it up to date with dev by rebasing it on top of dev, effectively applying all the changes contained in it to the current state of dev. If rebasing is impractical one could merge dev into a topic branch to get access to some features that were not available when the branch was started. However, merging dev into a topic branch “just to stay up to date” is not a good idea since it confuses commit history.

When a released version of the code needs a fix, a “bug-fix” branch is created from the main branch. When the implementation of a fix is complete, the bug-fix branch is merged into main (and main is tagged to mark the new bug-fix release) and into dev so that the fix is included in the next major release.

In https://github.com/pism/pism branches are named using the name of the person responsible for the branch as a prefix. For example, ckhroulev/pnetcdf is the name of Constantine Khroulev’s branch containing improvements of the I/O code using PnetCDF.

Note

Please commit all your changes to “topic” branches. The main and dev branches are managed by PISM developers at UAF.

Footnotes

1: This model may not be perfect but works well for a project of PISM’s size.
2: See Fun with merges and purposes of branches by Junio C Hamano for more about “topic branches.”