Branches, Tags, and Versions

This document discusses the rationale behind the way the Shibboleth team branches and tages code in a project's SVN 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 TRUNK the trunk until the product was ready to be released. Prior to release, a branch was created from TRUNK. This branch was 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 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 TRUNKthe 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 has currently been occurring within the TRUNK of these new repositoriesdone prior to the conversions to git occurred on trunk and is now occurring on master.

Current Branching and Tagging Practices

This current policy on branching and tagging makes two assumptions:

• the Shibboleth The project will not have the developer resources to actively develop more than one major release of a given product at a time.
• the Shibboleth project wishes 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 would 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 TRUNKtrunk/master.
• When a new patch version is created, a new released, tags are created from wherever the work for that release was done.
• A branch is not generally created. Bug fixes continue to be applied to TRUNK.Prior to work starting If after work begins on a new major/minor release, it becomes necessary to produce a patch release, a branch for the current minor version is created.Tags, representing a released version, are generated from the branch/TRUNK associated with the minor releasethen created from the original tag for the release being patched, and any fixes warranted from master/trunk are backported/merged back at that time.
• Once the branch exists, bug fixes must may need to be applied to both the branch for the current previous stable minor release and TRUNKmaster/trunk.

This "late branching" policy should minimize the amount of time that bugs need to be fixed in both TRUNK and a release branch and hopefully nearly eliminate cases where the TRUNK has changed significantly in the area that such a patch would need to be appliedtwo places.

Effect on Maven POMs

During development, our Maven POMs use the first two components of the version identifier concatenated with -SNAPSHOT (e.g., 2.3-SNAPSHOT). 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.

In the past, a Shibboleth project that relied on another Shibboleth project would rely on the snapshot of a given patch version. The major downside of this approach is that once that version is released the snapshot goes away. This, in turn, breaks all projects whose POMs referenced the snapshot. Since no new features or APIs are added within a minor release stream it's safe to reference any given snapshot within that stream. And, since such snapshots never go away, projects which reference them never contain broken references.

Here's an example of how this relates to the late-branching policy noted above:

...

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.