Versioning and tagging bundles and modules - practice and process

[leingang]

I have a bundle of several modules, and I haven't quite figured out how to assign version names. One of my options doesn't seem to be working in my l3build configuration, which makes me wonder if it's discouraged.

The unexpected behavior is: if I do l3build tag <name> in the top level (bundle) directory, l3build descends into the first module (in the modules table) to tag the files, then exits. I thought it would visit all the modules for tagging, or only the files in the bundle level.

Now to the questions:

Should the bundle and all its modules have the same version number, or should each module and the bundle have separate versions? I like semantic versioning, and it makes sense to for each module to have a separate semantic version (otherwise a modules version changes even if the code changes are in another module).

It makes less sense to me for the bundle to have a semantic version, since other than the modules it really only contains documentation. So perhaps date versioning is better for the files in the bundle that don't belong to a module.

Then, what should be the relationship between the version and any git tags? Git tags are attached to the entire repository, so if you want the git tag to be the version name, everything has to have the same version name.

Maybe instead each time module foo gets a new version, the repo gets tagged foo-<version>. But if the bundle files change, the repo gets tagged bundle-<version>. That's complicated, but the build.lua script ought to be able to handle it.

I am pretty sure that the LaTeX3 project uses date versioning for everything, including tags. And maybe one reason for that is it makes this question very easy to answer. But I know many other packages have semantic versions, and some of those are probably kept in bundles, so I'm wondering if there are other conventions.

I haven't made any releases of these modules (only using them for personal use) so this is still theoretical. But at some point I'd like to share them with coworkers or CTAN. Any advice would help.

[josephwright]

As you observe, the team tend to use date-like strings for bundles. (Formally they are not actual dates: we use nominal values typically at the start or middle of the month.) Within bundles, of course, you can do what you like: that doesn't have to be automated or could be done using a more complex script.

Taking LaTeX2e's tools as an example, this is a 'module' which has a nominate date that appears only in the README.md file - we do that as CTAN want something in the upload to contain the nominal date string. Each .dtx within tools is entirely hand-versioned: this is partly because the history of LaTeX2e predates current version control practice, and so we expect all changes to be marked up (and thus typeset in the sources).

An alternative approach is seen in the l3experimental bundle. Again this has a date-like version string, but in this case we use the same string in all of the components. Thus here we do use l3build to set the values: I do that just before releases.

The point is that there is no one 'right' approach here: you just have to pick something. Bundles of course don't align well with 'one tag per version per release', so if that's what you want you are better splitting up entirely. Assuming you are going more for a mono-repo (which can make a lot of sense), then choose a scheme that works best for you. I think that a semantic version string for a bundle with semantic version strings for each module is likely a bit confusing, so I'd go with one of

• Nominal date for the bundle, independent versions for the components (could be semantic or date like or classical LaTeX vX.Ya)
• Nominal date for the bundle and matching nominal date for the components

as both of these work reasonably well.