RevisionSystem - coin-or-foundation/tlc GitHub Wiki

This page is about creating a suggested release/development standard that can be used as a basis for binary distributions and for external dependency management. The proposals have names of fish commonly used for sushi because numbers, letters, or colors have an implicit ranking, and I had sushi for lunch today :). These are the current proposals:

Mackerel

  1. Active development happens in Project/trunk
  2. If desired, there is also a Project/test directory, which contains code that is almost ready to be the next release, and can be used by users that help searching for bugs and installation problems.
  3. The most recent official release is put into Project/latest. Regular users would be asked to get the code from here, and tarballs would be created from that version. We should refer users always use the same URL, so that on their side an svn update will work.
  4. If a new release is put into Project/latest, it is also "tagged", by copying it into a subdirectory of Project/releases/, e.g., Project/releases/1.0.3. This copy is NEVER CHANGED! (Otherwise we cannot reconstruct particular revisions easily)
  5. Further, we have Project/branches, into which we can just put whatever branch we want, e.g., for experimental code, or a temporary branch to fix a bug in an older previous minor release; e.g., if the current verison is 3.2.1, and there is a bug in 2.9.15 which the project developer wants to fix (for a release 2.9.16), Project/test should not be used for temporary copies of 2.9.15 to fix that bug.

Tuna

For the purposes of this discussion, use hypothetical project Pkg with release number 1.0.3. The point of this proposal is to enable a binary distribution system.

  1. Active development in mainstream fetures (including new features planned for Mileston 1.0.4) happens in "Project/trunk".
  2. When release 1.0.3 is ready, an svn cp from the trunk to Pkg/tags/1.0.3 is made. Pkg/tags/1.0.3 is what will be used to create the binary or tarball version 1.0.3. At the same time, a branch Pkg/branches/1.0.3 is created, to fix bugs that might require a new release of version 1.0.3. Once those fixes are tested, and the PM feels they are significant enough for a new release, the process restarts with release 1.0.4.
  3. Development of experimental or otherwise nonstandard features takes place in Projects/branch/featureName or Projects/branch/1.0.3-featureName until it is ready to be merged into the trunk or discarded.
  4. PMs should clearly indicate in the documentation which versions of their package are considered supported, in the sense that effort will be expended in fixing bugs found in these versions.

Salmon (Ted's comments and a proposl)

  1. If we always copy the latest stable release into Project/latest and tell all users to check out from there, then they will be automatically upgraded if they do an svn update after a major release happens. However, as I understand it, part of the reason for stable releases is that an individual user may want to know that the rug will not be yanked out from underneath them when doing an update (i.e., the API will not change, they will just get bug fixes to their current version, etc.) So I guess we will have to tell users that if they just want to get bug fixes and not major releases with potential changes in the API, etc, then they should check out something from Project/releases (or wherever the stable releases live). Otherwise, they can just get Project/latest. This may be too confusing, though. An alternative is not to have a "latest" version at all, but just advertise what the version number of the latest stable release is. I'm not sure exactly which way is better.
  2. Assuming everyone is getting the code from SVN, I don't see any reason to have a Project/tags directory with static versions and a Project/branches directory with the same static version plus bug fixes, unless we expect people to actually check out the tagged versions. As I understand it, the purpose of tags is to allow the developers to know exactly what version of the code people are using, but if they check out version 1.0.3 from Project/branches, for example, and keep this version up to date with bug fixes, the developers still won't have any idea exactly what version they are using without asking what the SVN version number of their current code is. On the other hand, if they check out the tagged version, they won't get bug fixes unless they manually change to a different tagged version, and I don't think we can expect people to do that. This sort of defeats the purpose of using SVN.
  3. The only real use I can see for a Project/tags directory is if a developer wants to release static, stable tarballs that the user would download and would not be under SVN control. In that case, it would be useful to know that if the user downloaded the tarball version 1.0.3, we could immediately check out that exact version from SVN. This is more of a GNU release model in which most users are expected to just get a tarball and use it until manually upgrading to a new tarball, whereas use of SVN is reserved only for developers and power users. I think it may make sense for us to consider this model at some point, once we actually have "stable" version for most of the codes, but this is not what we currently have and may require a rethinking of all this. Our current model is still really aimed towards developers and "power users" more than "normal" users. Of course, "normal" users may only care about getting binaries anyway.
  4. Given the above arguments, I would prefer not to stick with the standard SVN directory structure. It still doesn't make perfect sense to me, even now that I understand subversion pretty well. It is an attempt to make subversion look a little more like CVS, but as already discussed, subversion doesn't even have a native concept of static tags. Given the choice, I think something simple and intuitive that one could look at without reading any instructions and know where to find things is preferable in my mind. I'm not completely settled on what that would look like, but here is one proposal.
    • Project/devel: where current development happens
    • Project/releases: Stable releases with bug fixes
    • Project/branches: A sandbox where any developer could create a branch to do experimental work without getting in anyone else's way.
  5. We could add a Project/tags directory later if we start to do static, versioned tarball releases. We could also have a Project/stable (or Project/latest) if that is deemed useful.

Humuhumunukunukuapuaa (Matt)

(Yes, it's a fish...)

The Subversion manual suggests the following strategy for managing releases:

  1. The main development line is in trunk/.
  2. To prepare a release, create a branch (in branches/), say branches/1.0, and copy from trunk.
  3. Release prep, QA, etc. proceed in the branch. Bug fixes in the branch can be pushed back to the main line, and vice versa.
  4. When the release is ready, create a tag (in tags/), say tags/1.0.0, and copy from branches/1.0. This release (as all tags) is frozen and never to change.
  5. Release maintenance proceeds in branches/1.0. To get the latest (unreleased) bug fixes, a user can check out HEAD from branches/1.0 at any time.
  6. Periodically, tag the current branches/1.0 HEAD as tags/1.0.1, tags/1.0.2, etc. as interim bugfix releases. Once tagged, these also are frozen, never to change. Maintenance continues in branches/1.0.
  7. Eventually, a new release will be planned that bumps the minor or major numbers. When ready, create branches/1.1 or branches/2.0 as appropriate and proceed as above.

Some comments:

  • 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, we 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 relese snapshot get fixed in the (two-digit) branch, as they need to be integrated into the current state of the release tree.
  • I'm not necessarily wedded to the trunk-branches-tags naming scheme, although it does follow the Principle of Least Surprise for other Subversion users. The main line could be in devel/, two-digit branches could be in stable/ (i.e., only bug fixes), and the three-digit tags in releases/. Whether tags/ or releases/, though, 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.
  • There's no easy way to get the "latest stable" across a release boundary, but I'm not sure that's a bad thing. In fact, I'm pretty sure it's not a bad thing. Changing a major or minor release number out from under someone blindly checking out "latest stable" is likely to break something. (People who check out devel/ deserve what they get.)
  • Tarballs could come in three flavors: release (fixed), stable's HEAD (nightly latest unreleased bug fixes), and devel's HEAD (use at own risk).
  • "Feature branches" where out-of-main-line development occurs could come and go in branches/ as needed. They get merged back into the main line when development is done.

I think this makes pretty good sense. (It was thought up by better men than I...) And I think it deals with most of the unclear bits of the other proposals.