git version tags

[Brian J. Tarricone]

Hi all,

I'm in procrastination mode, so it's bike-shedding[1] time!

As most of you know, currently when you build from svn, the version 
number that gets embedded into (most) binaries looks something like 
"2.6.1svn-r30400".  With svn, this is nice, because you can do version 
checks based on simple numeric comparisons because the svn revision 
number is monotonically increasing.

Git of course doesn't do that.  Git "revision numbers" are SHA1 hashes 
that represent the commit object, and you can't figure out ordering 
based on that.  However, the SHA1 hash does uniquely identify a 
particular commit.  And usually you can just take the first 6-8 
characters of the SHA1 hash and that's still unique.  (I'll represent an 
8-char SHA1 fragment as a series of eight 'S' characters.)

So, with git, we have a bunch of options:

-> X.Y.Zgit-YYYYMMDD-SSSSSSSS

* Pros: you can order a build with day-precision, and it still contains 
enough info to identify the proper commit if you need to do so manually.
* Cons: it's really kinda long.  We've gone from 10 chars with svn to 21 
chars with git.  And it's not perfect: you can't do version ordering 
among builds made on the same day.

-> X.Y.Zgit-YYYYMMDDHHMM-SSSSSSSS

* Pros: you can order a build with minute-precision, and it still 
contains enough info to identify the proper commit.
* Cons: it's *really* long.  We're up to 25 chars now.

-> X.Y.Zgit-YYYYMMDD

* Pros: it's similar in length to a svn revision tag, and can be used 
for day-precision version checking.
* Cons: the SHA1 is missing, so it's hard to figure out which commit the 
build is based on if there was more than one commit on a particular day 
(very common occurrence).  Also similar problem as the first option with 
the precision of the version check.

-> X.Y.Zgit-YYYYMMDDHHMM

* Pros: decent length, minute-precision version checking.  In practice 
you can probably figure out the exact commit the build is based on.
* Cons: it's still a bit long, and again you lose the exact commit.  In 
the case where someone checks in something, and *immediately* notices a 
mistake and makes another quick check-in (in under 60 seconds), this 
could thwart version checkers (but in practice this might not ever happen).

-> X.Y.Zgit-SSSSSSSS

* Pros: it's a reasonable length, and lets us uniquely identify the 
commit that the build is based on.
* Cons: we lose all ability to do version order checking.  All we can 
say is "this build is after X.Y.Z but before X.Y.(Z+1)".

-> X.Y.Zgit

* Pros: it's super short, and conveys a very useful bit of information: 
"this is a development build".
* Cons: lack of version order checking identical to the above case, no 
way at all to figure out which git commit was used to make this build.

We can of course come up with other combinations.  We could add two 
characters for the seconds value of the commit time.  We could probably 
shorten the SHA1 fragment to 6 chars instead of 8.  We might even be ok 
dropping the first two digits of the year since at this point git 
revisions between two actual releases are unlikely to span a century change.

But I guess the problem boils down to two questions:

1.  How important is it to maintain the version-order-checking ability 
that we have with svn?  If it's really important, we'll have to 
incorporate one of the date-based schemes.

2.  How important is it to be able to identify the exact git commit that 
the build is generated from?  If it's really important, we'll either 
need a SHA1 fragment, or we'll need to decide if minute-precision (or 
second-precision) on the date in the revision tag is enough.

(I'll note that when we used CVS, we didn't put a date or anything in 
the revision field [we just used "X.Y.Zcvs"], and the world didn't end.)

	-brian

[1] http://en.wikipedia.org/wiki/Bike_shed