-
Notifications
You must be signed in to change notification settings - Fork 43
Release Process
This page describes the process of release. It should be carefully studied before attempting to release a Gregorio version.
This page describes the general release process, for technical details, see the release actions.
Gregorio uses Semantic Versioning. A priori, major releases are not maintained after a new major release is out. This means that, for instance, when 4.0 is released officially, 3.X becomes obsolete and support for stops.
It seems a good practice to release every few months, if user-impacting changes have occured in the repository.
Gregorio uses the Gitflow workflow. All developments take place in separate branches, and once they are ready for a release, they are merged in the develop or ctan branch. Developments which only alter the tex (and lua) files and which do not require a major release (change to x+1.0.0) are allowed on the ctan branch. All other development should be against the develop branch.
During the course of the year, new releases which can be uploaded to CTAN are made off the ctan branch.
Each year, in either January or February, a new release based on the develop branch can be made. This release should not be uploaded to CTAN until the TeX Live pretest is announced, at which point it should be uploaded with a note that it is specifically for the pretest and should not be added to the current year TeX Live.
Once a release is decided, a new release-x.y branch is created, based on the develop or ctan branch. New features continue to arrive on those branches, but are not merged into release-x.y.
Version changes are only made in release-x.y or hotfix-x.y.z+1 branches. No changes are to be made in the develop, ctan, or master branches.
In some cases, new features may require an extended beta period in order to iron out possible kinks "in the wild." In this case, these extended beta releases can be created directly on the develop branch and their creation does not feature lock the release. Once the feature set has stabalized, then the release-x.y branch is created and betas (or release candidates) continue there.
Once the release-x.y branch is created, the version is incremented in the branch, using VersionManager.py with either -m or -e to increment the major or minor number respectively. The new version is x.y.0-beta1.
Once the hotfix-x.y.z+1 branch is created, the version is incremented in the branch, using VersionManager.py -p. The new version is x.y.z+1.
Once the branch is considered stable enough for release, it can be tagged (by git) as vx.y.0-rc1 and released (as described in the release actions). Users are informed of this release and can test it if they want. If blocking bugs are discovered, a new release candidate is released (vx.y.0-rc2), etc.
Once the blocking bugs are fixed, the vx.y.0 version is released. The release-x.y git branch is merged into master, develop, and ctan.
In order to ensures that new deprecations will not get mixed in with the old ones which need to be advanced prior to the next release, after the merge of a major or minor release it is advisable to create a deprecation branch and step deprecated and obsolete functions along the deprecation path right away. A separate commit should be made on this branch for steps that would happen only a major release. In this fashion those changes can be reversed should the next release turn out to be a minor release.
If bugs are discovered, new versions can be released anytime before the x.y+1.0.