[boost] Versioning of individual modules

Subject: [boost] Versioning of individual modules
From: Peter A. Bigot (pab_at_[hidden])
Date: 2013-12-30 12:32:14

Forked from Re: [boost] [git] tagging in modules

Context below.  Guided questions follow the quoted context.

On 12/30/2013 11:02 AM, Beman Dawes wrote:
> On Thu, Dec 26, 2013 at 7:24 PM, Peter A. Bigot <pab_at_[hidden]> wrote:
>
>> Not relevant to the original thread, but since I just noticed it:
>>
>> git-push by default does not push tags: you need to specifically ask for
>> the tag to be pushed (by name), or use --tags.  So this sequence does
>> nothing visible:
>>
>>   git tag -a 1.2
>>   git push
>>
>> Personally I'd prefer if tag symbols were a little more informative than
>> "1.2", and followed a pattern that places them in a namespace reserved for
>> the module, such as timer-1.2.  Because tags aren't normally pushed,
>> they're useful for individual developers to use as markers.  However,
>> git-pull will automatically retrieve tags attached to commits that are
>> fetched unless --no-tags is given, so if a repository (from boostorg, or
>> another developer) defines (or moves) a tag it might overwrite your local
>> tag without warning.  So it's important to know what tags you can expect
>> might conflict with those in a remote repository to avoid conflicts.
>>
> Updated:
>
> https://svn.boost.org/trac/boost/wiki/StartModWorkflow#Releasetags
> <https://svn.boost.org/trac/boost/wiki/StartModMaint#Lightweightlibraryrelease>
> https://svn.boost.org/trac/boost/wiki/StartModMaint
> #Lightweightlibraryrelease<https://svn.boost.org/trac/boost/wiki/StartModMaint#Lightweightlibraryrelease>
>
>
>> I'd also really like to see any module that uses internal versioning also
>> provide a mechanism by which code can determine which version is being
>> used.  E.g., for the above there ought to be a <boost/timer/version.hpp>
>> header which has:
>>
>> #define BOOST_TIMER_VERSION_MAJOR 1
>> #define BOOST_TIMER_VERSION_MINOR 2
>>
>> Otherwise I'm not seeing any value for module-level version tags in the
>> repository.  Matter of taste, though.
>>
> While I'm sympathetic, we should get comments and buy in from library
> maintainers before recommending this. Are a lot of libraries already doing
> something similar? If so, what? And do we follow Rene's suggestion and
> recommend Predef? Could you please start a separate discussion with a
> subject that let's maintainers know this is affects them? Thanks!
>
> There is a tangentially related issue: The git and modular boost related
> docs are being developed without any reference to or updating of existing
> developer documentation. We need to get that underway. Ditto web site
> changes.
>
>
>> I would expect, on superproject release, that each module would continue
>> to receive a boost-X.Y tag marking the module commit that corresponds to
>> the submodule SHA1 used for the release.  This is another reason to make
>> sure module-level tags are clearly distinguished (lest somebody think the
>> tag corresponds to a boost version rather than a module version).
>>
> Sounds about right, but we would need to work out the mechanics. Who does
> the tagging? A script release managers run?

General questions related to this topic:

*) When a module pushes to master, must all commits that appear directly 
on the master branch be considered "stable" or is it only necessary that 
the HEAD always be stable?

The context for this is actually in "[git] avoiding fast forward merges" 
at http://lists.boost.org/Archives/boost/2013/12/210110.php.  It's 
primarily a superproject decision but module maintainers should be aware 
of it.

*) Should all modules be assigned version numbers, or may module 
"releases" be unversioned master commits that "inherit" the Boost 
version when incorporated into a release?

My opinion: Don't bother unless there's clear evidence that the module 
will be shipped or used outside of a versioned Boost installation.

*) If a module has a module-specific version number, should it be 
expected to provide that version number in a standard location and name 
so that preprocessor directives interrogate and adapt user code based on 
it?  What mechanism should be used for this?

My opinion: Absolutely.  If the module is named timer (sorry I keep 
picking on that module), then I would like to see:

#include <boost/timer/version.hpp>

define a macro BOOST_TIMER_VERSION which has an ordinal integer value 
that may be used in comparisons in preprocessor conditionals to select 
available features.  I support Rene Rivera's suggestion to use the 
BOOST_VERSION_NUMBER macro from Boosts.Predef to accomplish this.

Of course, if no modules need module-level versioning, this won't be 
necessary.

*) What syntactic format should be used for git tags that record version 
numbers?

My opinion: If the module is named timer, and the version number is 1.2, 
the tag timer-1.2 would be created and pushed to the boostorg timer 
repository by the timer maintainer.

*) By what process is the superproject version associated with the 
commit on the master branch that is selected for a given Boost release?

My opinion: If the Boost release is 1.56, every module incorporated into 
that release has a boost-1.56 tag created, identifying the master branch 
commit that is incorporated into the release.  This tag would be added 
by the release manager when the superproject is tagged using a trivial 
"git submodule foreach git tag boost-1.56" in the superproject master 
branch followed by "git submodule foreach push origin boost-1.56" after 
sanity checks.

Other inputs?

Peter