Release Process
This page gives an overview of the development process, ie. how patches and branches are managed in the lead up to a merge window, during and after the merge window, until the final release is tagged by Linus.
Each release overlaps with the previous, ie. while release N is stablising and being tested through the rc series, the N+1 release is being prepared. The description here is for a single release, to try and keep the documentation simple.
Note on terminology, the "merge window" is the two weeks immediately following the previous release. It is the time when maintainers send pull requests to Linus. It is not when patches should be applied by maintainers.
For this explanation we will talk about the 6.8 release, but that is just an example to avoid having to write "release N" everywhere, what's described here isn't necessarily what happened with the 6.8 release.
IMHO the best time to begin preparing a release is rc2 of the previous
release, in our case v6.7-rc2. Using rc2 means everything from the previous
merge window should have been merged, and any critical bugs should have been
fixed prior to rc2. It is possible to use rc1 but that increases the risk of
hitting some unfixed bug.
If using the setup-repo script, it will have created the next, next-test
and next-base branches for you. Or if you have an existing repo from a
previous release it will already contain those branches.
🌟 We will use the
git ffwdalias extensively. It is created by thesetup-reposcript, or you can do it manually withgit config --replace-all alias.ffwd "merge --ff-only".
Fast forward all of those branches to the rc2 tag:
$ cd ~/src/linux
$ git checkout next-base
$ git ffwd v6.7-rc2
$ git checkout next-test
$ git ffwd v6.7-rc2
$ git checkout next
$ git ffwd v6.7-rc2
If any of the branches don't fast forward, that means there's something in that
branch that wasn't merged into v6.7-rc2. That should never happen for next
or next-base. For next-test it may happen if some commits were applied for
testing but then weren't merged for some reason. It's possible to rebase any
commits onto v6.7-rc2 to bring them along for the new release, or reset the
branches to throw those commits away.
In the usual case (no rebasing) all three branches will now point at v6.7-rc2.
The three branches each have a separate role.
next-base is never changed and just points to v6.7-rc2 until the next
release. We could do without this branch and just use the rc2 tag, but it's
convenient and less error prone to have a named branch which identifies where
our next branched off from mainline.
next-test is where patches are applied from patchwork or the mailing list.
Once in next-test the patches can be set to Under Review in patchwork.
Patches exist in next-test for a few days to a week while the branch gets some
testing, via manual testing or the various CIs. next-test may be rebased or
reset to modify or drop patches.
next contains commits that have been tested and are now destined for the next
merge window. next is included in Linux Next as the "powerpc" tree. Patches
should not be applied directly to next, it should only be updated by fast
forwarding it to a commit in next-test (usually the tip, but not necessarily).
next should not be rebased unless absolutely necessary.
Once the branches are established patches can be applied as they appear on the list and pass review. The first weeks of the release cycle are the ideal time for larger features to be applied. That gives them the maximum time in Linux Next for testing.
Changes that touch generic code or other architectures or subsystems should also be applied as early as possible, so that they can be tested by those other subsystems and any issues can be coordinated between maintainers.
This is the primary time when feature patches are accepted for the release,
running from rc2 through to rc5 or rc6. As the later rc's approach the
size and impact of features that are applied should start to decrease, with the
exception of bug fixes.
It's also important to push patches to next semi-regularly so that they are
incldued in Linux Next. It's no good applying patches and then leaving them
unpushed for weeks.
🌟 Also worth noting is that the final Linux Next for the week is built
on Friday. But because sfr pulls trees early in the Australian morning that
means commits need to be in next by Thursday night to make it into Linux Next
for that week.
As the merge window approaches the content of next should start to stabilise.
Ideally all major features are applied, and only small fixes to those features,
or cleanup/spelling/etc. patches are applied in the week of rc7 (or rc8
if there is one).
At the same time it is worth remembering that patches applied prior to the merge window still have 8-10 weeks of the merge window and rc series in order to be tested and have any bugs shaken out. So small changes that don't affect other subsystems can be applied without too much stress in the final week.
The merge window begins when the previous release is tagged. That is usually on a Sunday (or Monday in the eastern hemisphere).
In our example that is the v6.7 tag.
It is possible to send a pull request prior to the previous release being tagged, but there is some risk of a late merge conflict appearing which the pull request will be ignorant of.
The actual timing of the pull request usually doesn't matter that much, but it should be sent in the first week of the merge window unless there is some late breaking issue that needs a little more testing.
The pull request should be prepared according to the pull request instructions.
Linus merges trees in some order of his choosing, not in the order they are sent. So the timing of the merge can vary.
Once the powerpc next branch is merged into Linus' master the focus switches
from new development to fixes.
As with the next branches there are three branches for handling fixes. As
above they should be created by the setup-repo script, or manually.
To begin with they should be made to point to the commit where Linus merged the
powerpc next branch.
That commit should have a title something like:
Merge tag 'powerpc-6.8-1' of git://git.kernel.org/pub/scm/linux/kernel/git/powerpc/linux
We'll call this commit the "original base commit". If that commit had a sha1 of
abcdefabcdef, the fixes branches should be setup with:
$ cd ~/src/linux
$ git checkout fixes
$ git ffwd abcdefabcdef
$ git checkout fixes-base
$ git ffwd abcdefabcdef
$ git checkout fixes-test
$ git ffwd abcdefabcdef
As for next, patches should be applied to fixes-test, then promoted to fixes
using a fast forward.
Unlike next, the base branch should move along as time goes on and fixes are merged into mainline.
The original base commit should be used for the remainder of the merge window,
ie. until rc1.
If an important fix is required after the merge of next but before rc1, it
should be applied to the fixes-test branch based on abcdefabcdef. It should
then be sent to Linus before rc1 is tagged.
Then once rc1 is tagged the three branches can be fast forwarded to rc1, eg:
$ cd ~/src/linux
$ git checkout fixes
$ git ffwd v6.8-rc1
$ git checkout fixes-base
$ git ffwd v6.8-rc1
$ git checkout fixes-test
$ git ffwd v6.8-rc1
For the week of rc1 any fixes should be applied based on rc1, and then sent
to Linus.
Once rc2 is tagged, the branches should be fast forwarded to rc2:
$ cd ~/src/linux
$ git checkout fixes
$ git ffwd v6.8-rc2
$ git checkout fixes-base
$ git ffwd v6.8-rc2
$ git checkout fixes-test
$ git ffwd v6.8-rc2
But we don't move past rc2. That is because we will have forked next etc.
from v6.8-rc2 for the v6.9 release, and it is helpful to have the base of
the next and fixes branches to be the same from the on.
So for the remainder of the release any fixes are applied based on rc2.
Roughly every week (if there are fixes outstanding) a tag is created and a pull
request is sent to merge the outstanding fixes.