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), development was performed on 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 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 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 repositories.

Current Branching and Tagging Practices

This current policy on branching and tagging makes two assumptions:

• the Shibboleth project will not have the developer resources to actively develop more than one release of a given product at a time
• the Shibboleth project wishes 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 provide bug fixes for 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 TRUNK.
• When a new patch version is created, a new branch is not created. Bug fixes continue to be applied to TRUNK.
• Prior to work starting on a new major/minor 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 release.
• Once the branch exists, bug fixes must be applied to both the branch for the current minor release and 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 applied.

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). 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:

• When development for minor version 1.3.0 is occurring on TRUNK, the POM version is 1.3-SNAPSHOT
• When development for minor version 1.3.X moves to a branch (because the next new minor release is being started on TRUNK), the POM version in the branch is 1.3-SNAPSHOT and the POM version in TRUNK becomes 1.4-SNAPSHOT
• When patch version 1.3.5 is generated, the POM version remains 1.3-SNAPSHOT in TRUNK/the branch and is 1.3.5 in the POM file associated with the 1.3.5 tag.