Branches, Tags, and Versions

Owned by ChadC
Last updated: Sept 07, 2021 by Scott Cantor

This document discusses the rationale behind the way the Shibboleth team branches and tages code in a project's repository and the impact that has on things like version numbers and project POM files.

Before proceeding, please review the Shibboleth Java product versioning policy to find the definition for terminology used in this document.

History

In the previous major development cycle (OpenSAML v2, CDS v1, IdP v2), which was in subversion, development was performed on the trunk until the product was ready to be released. Prior to release, a branch was created to represent a stable, supported set of code going forward. When a new set of destabilizing development was to begin, all changes from the branch were to be merged over to trunk and the destabilizing work was to be done there.

This process presupposed that the Shibboleth development team would have enough developers to maintain two parallel tracks of active development. That never occurred; instead, the developers simply tried not to make any destabilizing changes (and were moderately successful). As such the release branch was never merged back on to the trunk.

When the next major development release began, the decision was made to move to multi-module Maven projects for OpenSAML and the IdP. Therefore, new repositories were created and the three libraries in the OpenSAML stack were merged in to the new OpenSAML repository, likewise for the two IdP libraries and the new IdP repository. All work done prior to the conversions to git occurred on trunk and is now occurring on "main".

Current Branching and Tagging Practices

This current policy on branching and tagging makes two assumptions:

  • The project will not have the developer resources to actively develop more than one major release of a given product at a time.

  • The project may wish in rare cases to offer bug/security fixes for the previous minor version of a given product (e.g., if the given current release of the IdP is 3.2.X, than the developers might occasionally provide bug fixes for both it and 3.1.X).

Therefore, our products use the following branching and tagging practice:

  • Development of a new major or minor version is initially performed on the "main" branch.

  • When a new version is released, tags are created from wherever the work for that release was done.

  • A branch is not generally created. If after work begins on a new major/minor release, it becomes necessary to produce a patch release, a branch is then created from the original tag for the release being patched, and any fixes warranted from "main" are backported/merged back at that time.

  • Once the branch exists, bug fixes may need to be applied to both the branch for the previous stable minor release and "main".

This "late branching" policy should minimize the amount of time that bugs need to be fixed in two places.

Effect on Maven POMs

During development, our Maven POMs use snapshot versions containing the entirety of a given branch's next expected version. One Shibboleth project that depends on another can therefore reference the latest code for a given minor release stream. During the release of a product a specific released version of the dependent product is chosen. At that time, the POMs are updated to a newer snapshot version. At times after a release, the actual inter-project references may be in varying states of referencing the previous tagged version or the next snapshot.