Versioning builds from repos

[Mads Kiilerich]

Mercurial and other projects using Mercurial have similar challenges 
when it comes to versioning of local builds and official releases. It is 
a bit annoying that everybody has to invent their own solution, and none 
of the solutions are good. And Mercurial itself uses (at least) two 
different methods; the one in setup.py and the one in contrib/buildrpm. 
We really should use the same method both places and make it good. 
Assuming one size fits all.


I have tried to draft an overview of the problem as I see it:


It is very nice - almost a requirement - that version numbers from any 
(non-stripped) repo always should be increasing. It is especially 
important for auto-built and auto-installed packages that upgrades can 
be handled differently than downgrades.

It is also important that versions numbers are readable and makes sense 
to users/administrators.

And finally the version number should uniquely identify the content. 
That is a hard (impossible) problem, especially with DVCS where 
everybody have their own branch which progresses in its own tempo and 
where "releases" can be made independently at any time.

For these reasons a revision hash is bad as version number. But the hash 
has the advantage that it uniquely identifies the changeset even though 
it doesn't say anything about where it can be found, so it is fine as 
the insignificant last digits in a version number.


Mercurials setup.py will currently - when run from a Mercurial working 
directory - run hg id on the current revision and parse its output and 
write a tag name or hash id to mercurial/__version__.py. These numbers 
are thus not increasing and gives no hint about what released version 
they are based on.

Official released Mercurial tar balls contains (or should contain) the 
correct version number in __version__.py, probably a tag name written by 
setup.py.

When setup.py is run from a plain "hg archive" tar ball then it could 
perhaps use the node id from .hg_archival.txt for unique identification. 
There won't be any good increasing version numbers, but that would be 
better than nothing ...

contrib/buildrpm must be run from a repo and generates an increasing 
version number from what seems to be the latest tag name and the number 
of changes added to the repo since. These numbers are readable and 
increasing. It is however done quite inelegant from a shell script, and 
the version number isn't deterministic and reproducible.

For "nightly builds" the date can be used as an increasing version 
number. But this scheme breaks down if one day more than one build has 
to be made. And such version numbers are not related to the repo content.


Something like the "nearest" extension could perhaps be useful. Longest 
distance to an official tag seems to be a good measure. Perhaps that 
extension could be distributed with Mercurial and used, or a lightweight 
version could be built in?

Obviously any good technical method would have to adjust or be adjusted 
to conventions for how tags are used and how releases are made.

I think it would be nice if both the rpm version and the version 
reported by hg could be something like "1.2.1-917-f0a7accf1d68".

Do you have any thoughts or comments about this?


/Mads