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, etc.) is given a version string equal to the release date expressed in ISO format, e.g. 2020-02-02. If at all possible, the patch levels here stay in line with the kernel: if we need a patch for one of the required set without a kernel release, we normally add a letter (so for example 2024-11-01 patch level 1a).

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, etc. Updating only this required component

Note that all of the code is contained within a single repository; tagging as release or dev builds the full set, whereas tagging with a name of a required part only builds those files.

When tagging patch levels or pre-releases, we use :<n> after the ISO date, for example dev-2025-11-01:1 would be the first pre-release of the kernel for an upcoming 2025-1-01 nominal release date. (Earlier, we used -PL<n> on main and -<n> on develop, but this is then hard to match up with l3build tagging!)

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-. (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 setting the patch level on main to 0 (the version string will be update from develop)
• 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
• 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 (this should be the case, but it is worth checking)
• Add the changes to the merge commit
• Tag using git tag -a -m "" release-<ISO>
• Switch to the develop branch
• Merge from main to develop
• Update the version strings in develop using l3build tag <next-ISO>:0 in base and the required set
• Commit these changes with message Step release tag
• 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