skip to Main Content
Managing Singularity Branches

Managing Singularity Branches

Greetings Singularity community!

Based on a lengthy discussion about code organization during February’s hackathon, Singularity’s repository branches at will soon be reorganized. There are two main reasons to do this:

1) To reduce confusion about which branch developers to submit pull requests.
2) To clarify that transition from the Python/BASH code base to Golang.

Perhaps the biggest change will be the removal of the development branch. A master will take the place of development, and will be the default target of new pull requests. If you install from master, you will get the latest, bleeding-edge version of Singularity. If you would rather have a stable version of Singularity you should install from one of the tarball releases or from a tag instead of a branch. A detailed description of the new branch organization follows.

Here is the proposed git tree as discussed in the February Hackathon:

  • development-2.x
  • development-3.0
  • master
  • release-2.4
  • vault/1.x
  • vault/2.x
  • vault/release-2.0
  • vault/release-2.1
  • vault/release-2.2
  • vault/release-2.3

General workflow

  • The master branch is the current view of the project development and is the default branch to clone from github.
  • All new development git commits are created against this branch.
  • When a new release sprint is started, only bug fixes goes into master and release candidate (-rcX) tags are created until a release is finally tagged from master.
  • When a release tag is created, a new branch with the name of the release (release-X.Y) is created and this constitute the new stable branch.
  • A release branch (release-X.Y) is maintained as long as needed, and for each patch level release, a new tag conforming to the semver standard (e.g., v2.4.5), and preferably signed, is created when the last release candidate tagged commit has been approved for release.
  • Bug fixes for maintained release branches are developed and tested on the release branch it’s targeting first. The commit is then applied to the developer’s master branch (if needed), tested again and submitted for inclusion into the current development.
  • Note that this general workflow also applies to transitional branches (development-2.x, development-3.0) described below as it does here for master.

Notes on other transitional branches

  • development-2.x is the current development branch for the 2.x series. This means that development-3.0 was forked, and development should not be used anymore. All new features and bug fixes for the current production release of singularity should prepare pull requests targeting development-2.x and not the development branch anymore. The result of the work done against that branch will be new production releases such as 2.5 and 2.6.
  • Finally the end goal is to deprecate development-2.x as soon as release-3.0 is ready, and established as the new maintained production branch.
  • development-3.0 is a temporary branch. It’s purpose is to bring up our early development to a stage where it is acceptable to be merged into master. It is also a community tool for transparency and encouraging dialog and early development from the community. This branch doesn’t produce a working singularity program yet. development-3.0 will be deleted or moved into the vault workspace after being merged into master.
  • All branches not shown in the above picture will be deleted from the current singularity tree.
  • All branches moved into vault/branchname are older releases that we keep as archive for reference. As we roll from a set of maintained releases to the next, we move the unsupported release branches into the vault workspace.

Singularity release pace

  • After defining the proper structure of our git tree, it’s important to define the proper release pace of open-source releases.
  • Opening of window of pure development for about 1.5 months followed by a stabilization phase with release candidates and a final release allows us to create good features while balancing with a tree holding correct, functional and stable code.
  • The guideline is to come up with a release every 2 months but with necessary adjustments based on the quality of the code and the readiness of the release as opposed to a set-in-stone date.
  • The advantage of that model is that the developers have now a way to expect when new releases will come and helps with integration and deployment schedules. It also synchronizes the team to work in concert in turn on development, bug fixes, release and deployment.

This week’s post is a bit different from the last but we wanted to take this opportunity to bring you through the various angles of our progress. We look forward to hearing from you at via our Slack channel, the GitHub repository or Google Groups via


Back To Top