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@pabigot.com> 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
On 30/12/13 18:32, Peter A. Bigot wrote:
*) 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?
git describe --tags could be the right mechanism for this. If you're on a tag, it gives you tagname. Otherwise it gives lasttagname-numberofcommitssincethen-sha1.
My opinion: Absolutely. If the module is named timer (sorry I keep picking on that module), then I would like to see:
I have a question about this: Should module-specific version numbers start at 1.56, or whatever the last Boost version before modularization was, or should they start at 1.0?
On 12/31/2013 08:10 AM, Mathias Gaunard wrote:
On 30/12/13 18:32, Peter A. Bigot wrote:
*) 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?
git describe --tags could be the right mechanism for this. If you're on a tag, it gives you tagname. Otherwise it gives lasttagname-numberofcommitssincethen-sha1.
That's fine at the command line or scripts that produce an archive. The need here is to be able to tell within code whether a feature is available based on the version of the module. E.g: #if BOOST_TIMER_VERSION < BOOST_VERSION_NUMBER(3,5,2) /* provide local workaround */ #else /* use feature added in version 3.5.2 */ #endif
My opinion: Absolutely. If the module is named timer (sorry I keep picking on that module), then I would like to see:
I have a question about this:
Should module-specific version numbers start at 1.56, or whatever the last Boost version before modularization was, or should they start at 1.0?
Seems like something that Boost would normally leave up to the module maintainer, including whether the scheme selected is a two-value, three-value, or date-based versioning. I can imagine cases where a Boost library provides a wrapper around an external library that has its own versioning, and the two should be correlated. Peter
On 31/12/13 15:49, Peter A. Bigot wrote:
On 12/31/2013 08:10 AM, Mathias Gaunard wrote:
On 30/12/13 18:32, Peter A. Bigot wrote:
*) 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?
git describe --tags could be the right mechanism for this. If you're on a tag, it gives you tagname. Otherwise it gives lasttagname-numberofcommitssincethen-sha1.
That's fine at the command line or scripts that produce an archive. The need here is to be able to tell within code whether a feature is available based on the version of the module.
That output can easily be parsed to do whatever you want. It's important to keep in mind what this generates though, and how it could be mapped to a macro.
Seems like something that Boost would normally leave up to the module maintainer, including whether the scheme selected is a two-value, three-value, or date-based versioning. I can imagine cases where a Boost library provides a wrapper around an external library that has its own versioning, and the two should be correlated.
Wouldn't that be confusing for users?
participants (2)
-
Mathias Gaunard -
Peter A. Bigot