Releases: version strings, tagging and building

Version strings

As each part of the core LaTeX2e set up contains multiple files with independent version numbers, the bundles themselves are given overall version strings rather than expecting each source to report the same version number.

The kernel itself (latex2e/base)

Each major kernel release has a nominal date given in ISO format, e.g. 2020-02-02. This is not necessarily the date the release is finalised, but will typically be close to it. In general, we prefer to pick the 1st-of-month unless there is good reason (for example if we are going to release right in the middle of a month).

Patch levels (hotfixes to kernel major releases) retain the same nominal date and are marked as patch level, starting a 1 and incrementing. ('Patch level 0' is the initial major release of a cycle.)

Required bundles (latex2/required/...)

Each release of a bundle (amsmath, cyrillic, graphics, tools) is given a version string equal to the release date expressed in ISO format, e.g. 2020-02-02. Patch levels are not used unless there is a direct link to a kernel patch at the same time.

Tagging the sources

To update the sources (in particular the README.md files), run

l3build tag <string>

in the appropriate directory.

For the kernel itself, patch levels are given as a :<number> addition to the ISO date, for example

l3build tag 2020-02-02:1

for patch level one.

When on branches other than main, the same format is used to indicate a pre-release level, thus for example

git checkout develop &&
l3build tag 2020-02-02:3

would tag as pre-release 3 for kernel 2020-02-02.

Building releases

Building releases is set up automatically using the GitHub Actions system. This is triggered by creating a tag and pushing to GitHub. Git tags start with an identifier then the (nominal) ISO. Thus to create a full release one would use

git checkout main && 
git tag -a -m "" release-<ISO>

By convention, the tag identifiers are

• release A kernel release, which may include the required components
• dev A pre-release: used only on the develop branch
• amsmath, graphics, tools Updating only this required component

Note that all of the code is contained within a single repository, and tagging triggers Travis-CI to build all components (base, amsmath, cyrillic, graphics, tools). The naming of tags does not influence this at all.

When tagging patch levels or pre-releases, we use -PL<n> (main) or -<n> (develop) after the ISO date, for example dev-2020-02-01-1 would be the first pre-release of the kernel for an upcoming 2020-02-01 nominal release date.

After pushing the tag to GitHub, GitHub Actions will build zip files and send these back to be available as a new release or a pre-release: the latter happens for tags starting dev-. GitHub will always receive a full set of zip files (base, amsmath, cyrillic, graphics, tools) as the tag applies to the repository as a whole: which are to be sent to CTAN will depend on what is actually changed. (Uploads to CTAN are still done manually: the zip files(s) should be downloaded from GitHub then re-uploaded to CTAN in the normal way.)

Releases and pre-releases

When a release of the kernel or a required component is made, it is important that matching pre-release bundles are also made available. The reason is that latex-dev is always present in TeX Live and MiKTeX: see https://github.com/latex3/latex2e/issues/214 for more.

When there is no 'current' pre-release (for example, at the point a major release is made), the version string in the develop branch should match that in main. When there is a 'live' pre-release, the pre-release level will need to be incremented as part of the merge.

Major/patch release check-lists

The following steps need to be completed to carry out a major release of the kernel, committing and pushing only as detailed:

• Merge the develop branch into main, correcting any merge conflicts in favour of develop, but leaving version strings unchanged on main
• Check that all tests pass locally (do not push to origin at this stage)
• Manually edit the changes.txt files to move the development branch notice above the now 'live' changes, amending the merge commit to include this edit (this can be done by committing then rebasing or by amending directly)
• Run l3build tag <ISO> in base and each required directory which also has changes - this should be checked from the changes.txt files
• Manually edit the changes.txt to add the 'release' notice (in the #### blocks)
• Check that in ltvers.dtx, the main version is correct, the patch level is 0 and the development version data is empty
• Re-reun the checks: the release string will cause some to fail (e.g. rollback tests), so will lead to another round of updates
• Commit these changes with message Step release tag
• Tag using git tag -a -m "" release-<ISO>
• Switch to the develop branch
• Update the version strings in develop using l3build tag <next-ISO>:0 in base, required/amsmath, required/graphics and required/tools, checking that ltvers.dtx is correct
• Commit these changes with message Step pre-release tag
• Merge from main to develop, making sure (again) that the version strings in ltvers.dtx are not changed and checking and .tlg changes that show
• Tag using git tag -a -m "" dev-<dev-ISO>-0
• Push both main and develop and tags to origin
• Once GitHub Actions has build the release, download the main release zip file(s) and use these to upload to CTAN
• After a suitable delay, upload the matching dev pre-release to CTAN

Patch level releases follow a similar scheme but do not involve merging develop into main and so are simpler:

• Run l3build tag <ISO>:<n> in base and each required directory which also has changes - this should be checked from the changes.txt files (the value of <n> may differ between directories)
• Manually edit the changes.txt to add the 'release' notice (in the #### blocks)
• Commit these changes with message Step release tag
• Tag using git tag -a -m "" release-<ISO>-PL<n> (where <n> is the one for base)
• Merge from main to develop, making sure that the version strings in ltvers.dtx are not changed
• Update the version strings in develop using l3build tag <next-ISO>:<m> in base, required/amsmath, required/graphics and required/tools (where <m> may be greater or equal to <n>)
• Commit these changes with message Step pre-release tag
• Tag using git tag -a -m "" dev-<dev-ISO>-<m>
• Push both main and develop and tags to origin
• Once GitHub Actions has build the release, download the main release zip file(s) and use these to upload to CTAN
• After a suitable delay, upload the matching dev pre-release to CTAN