Standardizing Version Numbers and Stable Releases for COIN-OR Projects

Background

The following are the recommended procedures for versioning and releases for COIN projects. Note that these procedures are not required, but reflect a desire to have some standardization on the part the TLC. These are based on the "Humuhumunukunukuapuaa" (AKA "Triggerfish") proposal on the RevisionSystem page, which is in turn based on the "Release Branches" use case in the Subversion manual. The description below assumes some familiarity with basic subversion commands and the material on branching and merging in Chapter 4 of the manual. The description is modified according to the discussion in the 8/16/06 TLC meeting and the 8/29/06 TLC meeting.

Recommended System

1. Version numbering will follow the common convention of a triplet of numbers MM.mm.pp, where MM is the "major version number", mm is the "minor version number", and pp is the "patch level". Typically, version numbering for a new software project starts at 0.1.0, but "close to stable" versions get release numbers of 0.90.0 and up. The first stable release gets a major number of 1.0.0. Patches increment the last digit, and include only bug fixes. Enhancements that don't do major violence to the API increment the minor number. Major redesigns increment the major number.
2. The standard repository layout for COIN-OR projects will include the top-level directories trunk/, branches/, tags/, stable/, and releases/. The main development line will be in trunk/. "Feature branches" and miscellaneous tags may be created in branches/ and tags/, respectively, as suggested in the Subversion manual. However, use of these directories is optional. The stable/ directory will contain the development line for two-digit releases (mostly just bug fixes), while releases/ will contain frozen three-digit snaphots ("point releases") of stable versions (see description below).
3. To prepare a release, the project manager will create a branch (new subdirectory) in stable/ with major and minor version numbers, say stable/1.0, and copy the current code from trunk to stable/1.0. To accomplish this, in the working-copy root, the PM will execute

$ svn copy trunk stable/1.0
$ svn commit -m "Create stable branch 1.0"

If the PM does not wish to create a local copy, they can accomplish the same task remotely by entering explicit URLs:

$ svn copy http://projects.coin-or.org/svn/myproject/trunk http://projects.coin-or.org/svn/myproject/stable/1.0 -m "Create stable branch 1.0"

(See also [https://projects.coin-or.org/BuildTools/wiki/pm-svn-releases](https://projects.coin-or.org/BuildTools/wiki/pm-svn-releases) for information about scripts that automate the create of stable branches and releases.)
Subversion knows that the directory `stable/1.0/` contains a copy of the current revision in `trunk/`.  Modifications made to the trunk and this new branch are independent of each other, however.

1. Release prep, QA, etc. can proceed in the stable/1.0 branch. Bug fixes in this branch can be pushed back to trunk, and vice versa, as appropriate, while the release is being prepared. This is done with the svn merge command. For example, to copy a fix made in trunk in revision 344 to your working copy of stable/1.0 (from your stable/1.0/ working directory),

$ svn merge -r 343:344 http://projects.coin-or.org/svn/myproject/trunk

Then commit.

$ svn commit -m "Port r344 from trunk."

The revision number and source branch of the merged changes should (must) be recorded in the comments.  Copying patches back and forth can get confusing and there is no other mechanism for making sure that a patch isn't merged twice. Of course, patches can be merged the other way, too.

1. When the release is ready, the PM will create a tag in releases/, say releases/1.0.0, and copy from the HEAD of stable/1.0.

$ svn copy http://projects.coin-or.org/svn/myproject/stable/1.0 http://projects.coin-or.org/svn/myproject/releases/1.0.0 -m "Create release 1.0.0"

This point release (as all tags) is frozen and never to change.

1. After the first point release, maintenance continues in stable/1.0. To get the latest (unreleased) bug fixes, a user can check out HEAD from stable/1.0 at any time.
2. Periodically, the PM should tag the current stable/1.0 HEAD as releases/1.0.1, releases/1.0.2, etc. as interim bugfix releases. Once tagged, these also are frozen, never to change. Maintenance continues in stable/1.0.
3. Eventually, a new release will be planned that bumps the minor or major numbers. When ready, the PM can create stable/1.1 or stable/2.0 as appropriate and proceed as above.
4. Tarballs will be taken from the releases/ directory only. This will enable more accurate bug reporting based on a specific three-digit version number. Creation of a point release will automatically trigger the creation of a new tarball.
5. The project manager should use only point releases of other projects in the externals of a project's stable branches. This puts a minor burden on the project developer to keep up with releases of externals components, but it should be a conscious decision on the developer's part to force users to change releases of externals.

Additional Notes

• Once a snapshot is associated with a three-digit release number, it should never change. It is critical for reproducability that when a user reports a problem with release 1.1.4 (say), the PM can reproduce the version exactly with no other information. (Most users will have no other information.)
• Regardless of whether common users grab tarballs or check out of Subversion, the developers need to be able to recreate the exact code in a three-digit release in order to shoot bugs.
• Bugs found in a release snapshot get fixed in the stable branch, as they need to be integrated into the current state of the release tree. They may also be ported back to the trunk, if appropriate.
• It's a matter of project discipline to never check into a three-digit subdirectory. Whether Subversion has a notion of a tag or not is immaterial. We have a notion of a tag or release that is absolutely frozen.
• With the proposed system, there's no easy way to get the "latest stable" across a release boundary. Changing a major or minor release number out from under someone blindly checking out "latest stable" is likely to break something anyway, so this is probably the correct behavior. (People who check out trunk/ are willing to live on the bleeding edge and should be prepared to deal with this issue.)
• "Feature branches," where out-of-main-line development occurs can come and go in branches/ as needed. They get merged back into the main line when development is done. Tags not associated with releases are made in tags/. These also are never to be committed to.