If you're not a release manager, you don't have to care about any of this.
Our release branch workflow is:
- New feature development goes into master.
- Safe isolated additions, such as new drivers or UIs, may go into the stable branches at the discretion of the Release Manager.
- Bugfixes go into the oldest applicable stable branch.
- Stable branches merge upwards to master.
- Releases are made from stable branches.
- New stable branches are made from master when appropriate.
Creating a new stable branch
We aim for a new stable branch every 6-12 months.
How to make a new stable branch:
- Verify that master has a release tag in it named "vX.Y.0-pre0", where X.Y is the new stable branch that is being forked off master.
- Figure out what the new version number of master should be, "Z.W". For example, if you are making the 2.7 release branch, you might choose Z.W to be 2.8 or 3.0, depending on factors.
- Update the buildmaster:
- Add the new deb components to the applicable tools/generate-*.conf files.
- Create the new dists/$DIST/$COMP/binary-$ARCH directories and run tools/update-deb-archive $DIST.
- Update the buildslaves:
- Update /etc/apt/sources.list.d/linuxcnc-buildbot.list on all the buildslaves to know about the new debian components for the new stable branch (2.6-sim, 2.6-rt, etc). sigh
- Verify that apt-get update runs without problems.
- Create a new branch named "X.Y" from the tip of master, but don't push it yet.
- In the new "X.Y" branch:
- Update scripts/githelper.sh with the new release tag globs for master and X.Y.
- Optionally change what public keys are in gnupg/pubring.gpg (these are the keys that are allowed to sign release tags in this branch).
- Make a pre-release named "vX.Y.0~pre1" (see "Making Releases" below, this includes pushing everything so the debs get built etc).
- In master:
- Merge the X.Y branch into master.
- Verify that the githelper.sh release tag globs and keys in pubring.pgp are right.
- Make a pre-release named "vZ.W.0~pre0".
- Update http://wiki.linuxcnc.org/cgi-bin/wiki.pl?MinimumSoftwareVersions
- Make a new Live/Install Image for X.Y.
- Update the docs webpage at http://www.linuxcnc.org/docs
Making a new Live/Install Image
We have two Live/Install Images, one for RTAI and one for RT-Preempt.
Copy the new Live/Install Image to www.linuxcnc.org/iso.
If this is the first Live/Install Image for this version of LinuxCNC, add it to the Download page here: http://www.linuxcnc.org/downloads/
If this is an update to an existing Live/Install Image, update the checksums recorded in the Getting Started guide and on the website here: http://www.linuxcnc.org/downloads/
Prep work: write and translate the Updating instructions
A week or two before the release, update the appropriate wiki "updating" pages (http://wiki.linuxcnc.org/cgi-bin/wiki.pl?UpdatingTo2.5 and http://wiki.linuxcnc.org/cgi-bin/wiki.pl?UPDATING), and the User Guide document.
This document needs to explain any changes a user needs to do in order to upgrade to the new release version. Typically this is only needed for new major versions.
Notify the translators and let them translate the update instructions.
Do this work on the branch you want to release, for example "2.6".
- Find the version you want to release.
- Ideally make it so no one will commit to the release branch while you're working, but I'm not sure how to do this.
- Pick a version number. This must be a valid debian version number. For example: "2.4.7" "2.5.0~pre2". In the second example, notice that it is a tilde character, not a dash! In debian version numbers, X~Y sorts as less than X, so it works well in the "pre" role we use it for. Let's call this string "VERSION".
- Update debian/changelog. Make sure the version at the top is "1:$VERSION", so for example "1:2.4.8" or "1:2.7.0~pre1". An easy way to do this is to run dch -v $VERSION. In the editor, add a changelog based on the list of commits since the previous release. (Use something like this: git log --no-decorate --pretty=format:' * %s' $PREVIOUS..)
- Update the VERSION file to the $VERSION number you picked above, not including the "1:". So for example, "2.4.7" or "2.5.0~pre2".
- Commit but *don't* push.
- Make a signed, annotated tag named "v$(VERSION)", but with any tilde character "~" replaced with a dash "-", pointing at the commit you just made. For example "v2.4.7" or "v2.5.0-pre2". It should be signed with the Release Manager's key. So for example: git tag -u 'LinuxCNC Release Manager' -s v2.6.0-pre1 -m 'LinuxCNC v2.6.0-pre1'
Note that you might need to configure where the password is requested: https://stackoverflow.com/questions/49630601/signing-commits-with-git-doesnt-ask-for-my-passphrase
- Push both the branch and the new tag together, for example: git push origin 2.6 v2.6.0-pre1
- The buildbot will build and test, and put the packages in the release repo: http://buildbot.linuxcnc.org/release/
Writing Release Notes
Say if users need to make any config changes.
Include highlights from changelog.
Give credit to developers, documenters, & testers! You can list the people who wrote commits between two releases like this: git log --format='%aN' v2.6.12..v2.6.13 | sort | uniq
Put the new debs into the http://www.linuxcnc.org debian archive.
Create a new Post for the http://www.linuxcnc.org front page. Update the _data/releases.yml to point to the new release.
Update the #linuxcnc and #linuxcnc-devel topics.
Update the Released wiki page.
- News announcement on the www.linuxcnc.org front page
- E-mail to emc-users & emc-devel
- Wiki updates
If it's a major release (ie going from 2.5.x to 2.6.0), update the links on the Documentation part of the main www.linuxcnc.org webpage.