wiki:DM/Policy/ChangeTagScheme
Last modified 8 years ago Last modified on 03/21/2011 05:56:31 PM

Proposal to Change the Tag Numbering Scheme

This Proposal was commented upon but not put to vote. A subsequent revision of OnVersionNumbers updated the specifics of version numbering to include the current LSST DM Policy on number generation and advancement. 21 March 2011 RAA

Need

Currently DM modules are given a unique tag number, <Release>.<Major Version>.<Minor Version> where:

  • <Release> is the DM Data Challenge number
  • <Major Version> indicates a binary-incompatible API modification from the previous tag;
  • <Minor Version> indicates a modification which doesn't break binary compatibility with the previous tag.

When a tag component is incremented, all components to its right are set to zero.

The repartitioning of Data Challenge 3 into, first, DC3a and DC3b and then into DC3b PT1, DC3b PT1.1, DC3b PT1.5, etc, is foreshadowing the rapid increment of the <Release> id due to important intermediate benchmark Releases.

Proposal

A proposal is put forth to add a second component to the Release id: <Release Major>.<Release Minor> where:

  • <Release Major> identifies a major benchmark id which is roughly equivalent to the Data Challenge number;
  • <Release Minor> identifies a sub-challenge.

The definitions of <Major Version> and <Minor Version> corresponding to module modifications remain unchanged.

Transition to New Format

Usually, the transition from one Release to the next involves an initial retagging of all modules to the <<Release>.0.0> tag. During this period of tag format transition, tags will migrate from 3.x.y to either: 4.0.0.1 if the modification from the previous 3.x.y does not modify binaries; or migrate to 4.0.1.0 if the modification alters the API. Skipping the initial 4.0.0.0 tag allows us to retrofit DC3b PT1.1 startup tags from our existing (3.x.y) tag set should we later find that desirable.

At the commencement of DC3b PT1.5, all modules will be tagged with: 4.1.0.0 and subsequent modifications to a module's tag will follow the rules mentioned above.

Comments

K-T & Ray

On Wed, 25 Aug 2010, Kian-Tat Lim wrote:

I do not understand the justification for skipping 4.0.0.0. I

don't see any real reason not to tag the "PT1 production" versions as 4.0.0.0.

Except for the work of actually releasing all this productsw, which falls on my plate.

Though the tagger of a particular package may expect that the trunk has not changed, I shouldn't assume that it hasn't (or that the tagger didn't accidentally make a mistake). Consequently, I need to go through my usual testing.

My suggestion, which Robyn captured here, is that for the moment we restrict ourselves to tagging packages with real changes (which Robert, for one, wants to do soon). We can go back and tag unchanged packages later as needed.

On 2010-08-26 R Owen wrote:

Perhaps K-T is suggesting that you retag existing (well-tested) tagged releases as 4.0.x.x, not tag the trunk? If so, this sounds like a cheap and safe way to reduce confusion compared to running a mix of 4.x.x and 4.y.x.x. If we do go this route can we map 4.x.x to 3.0.x.x to get back to major version = data challenge version (but this might cause sorting issues). Looking ahead, I would prefer a numbering scheme that supports our current data challenges and also true releases (once in operation). Unfortunately with this scheme we'll need 5 fields, which is too many. Perhaps we can simply renumber everything down at that time.

RHL

I didn't see the numbers as tied to data releases, although they could be I suppose. I was proposing

  • Major release
  • branch
  • API change
  • Minor release

So if we branched 4.0.X.Y, the tip of the branch would become 4.1.0.0.

Also, I don't think it makes sense to try to sync up version numbers in products. If pex_exceptions 3.2.2 works, we shouldn't rename it to 4.0.0.0 just for the sake of tidiness --- after all, we've come to know and trust 3.2.2. I could see an argument for 3.0.2.2, but I don't find it compelling --- all trinomial versions implicitly have a .0

RLP

So if we branched 4.0.X.Y, the tip of the branch would become 4.1.0.0

That is to say, we could still release new 4.0.X.Ys even after 4.1.0.0 is released. I agree.

Also, I don't think it makes sense to try to sync up version numbers in products.

I'm inclined to agree with this as well.

RLP

OK, I've read the thread (in the airport) and I think I agree with the originalish proposal. I think that that is now:

tags from branches/PT1 should be 4.0.x.y tags from trunk should become 4.1.x.y if we create a branch for PT1.1, that will become 4.2.x.y trunk versions (PT1.5 development) become 4.3.x.y (starting at 4.3.0.0)

It means that we bump the 2nd number on trunk twice when we branch:

Once for the branch Once for the new trunk

Note that the branch requires two ops --- the new branch and the tag:

svn cp -m "PT1 branch" /DMS/afw/trunk /DMS/afw/branches/4.0 svn cp -m "Trunk at point of PT1 branch" /DMS/afw/trunk /DMS/afw/tags/4.1.0.0

(this tag means that svn ls /DMS/afw/tags will remind us of the new trunk convention, as well as recording when it happened) Russell's proposal even/oadd would require that we Only bump the trunk second number when we branch, which sounds OK but might be hard in practice. I agree with Robyn that we the developers can probably keep tabs on this.

One thing I might add is a file Branches at the top level (trunk) directory where the developer manually lists the tag decisions and why they were made. In cvs days this was needed, but I certainly found it helpful for more than branch merges. E.g.

Branched trunk for PT1 as 4.0. Tagged trunk as 4.1.0.0

PT1 (4.0):

Tagged 4.0.0.1 to fix RHL typo

Tagged 4.0.1.0 to fix dumb RHL ABI change

...

Trunk (4.1)

Tagged 4.1.0.1 to calculate w correctly

Tagged 4.1.0.2 to achnowledge Nobel committee

Branched trunk for PT1.1 as 4.2. Tagged trunk as 4.3.0.0

...

KTL

Robert wrote:

OK, I've read the thread (in the airport) and I think I agree with the originalish proposal. I think that that is now:

tags from branches/PT1 should be 4.0.x.y tags from trunk should become 4.1.x.y if we create a branch for PT1.1, that will become 4.2.x.y trunk versions (PT1.5 development) become 4.3.x.y (starting at 4.3.0.0)

No, this is Russell's proposal.

The original, original proposal was:

+ tags from branches/PT1 should be 3.x.y + tags from trunk should become 4.0.x.y + if we create a branch for PT1.1, that will become 4.0.x.y + trunk versions (PT1.5 development) become 4.1.x.y (starting at 4.1.0.0)

Note that the likelihood of additional branches/PT1 tags is very small.

It means that we bump the 2nd number on trunk twice when we branch:

Once for the branch Once for the new trunk

The original proposal would only bump once for the new trunk.

The branch would continue with 4.w numbers from the old trunk.

Note that the branch requires two ops --- the new branch and the tag:

svn cp -m "PT1 branch" /DMS/afw/trunk /DMS/afw/branches/4.0 svn cp -m "Trunk at point of PT1 branch" /DMS/afw/trunk /DMS/afw/tags/4.1.0.0

Since the branch point should be at a release (except for unused

packages still undergoing development -- and I wouldn't branch those), there should already be a tag of the trunk at the point of the branch. Having another tag in the new 4.w numbering seems redundant, although not too bad, and this reason may be sufficient to justify it:

(this tag means that svn ls /DMS/afw/tags will remind us of the new trunk convention, as well as recording when it happened)

Robert also proposed:

One thing I might add is a file Branches at the top level (trunk) directory where the developer manually lists the tag decisions and why they were made.

How is this different from an "svn log -v" of the tags

directory, which gives tag name, reason, trunk revision, date, and user? I'd hate to have yet another place to keep in sync.