How to prepare the git repo master branch for a kernel release

Description

This wiki page describes how to prepare the master branch of a git repository before releasing a new version of an Ubuntu kernel. The intended audience is Ubuntu Kernel Core Developers performing this task, or others interested in the process.

Repository Branch Structure

First, a word about the kernel branches:

master

master branch is the branch that should reflect exactly the release history of the package. The master branch should not be force pushed or rebased except to fix mistakes, and then only very rarely and carefully and after consultation with another kernel stable coredev

master-next

The master-next branch is where patches accumulate to be applied to the next release of the package. The master-next branch must have a common commit with master that is the previous tagged release, so that all new patches accumulate on top of what is released.

Preparing a release

A release is usually prepared using the master-next branch, pulling everything into master once everything's ready for release. It is necessary to make sure that the master-next branch is in a sane state. For example, it must contain the 'start new release' commit and, if required, the 'ABI bump' commit.

1. Check out a clean copy of the master-next branch

    git checkout master
    git fetch origin; git fetch origin master-next; git reset --hard FETCH_HEAD
    git clean -dxf

2. Review master-next commits Verify that the 'Start new release' and 'ABI Bump' commits have been correctly done in the master-next branch. If this has not been done, perform the following steps.

   1. Clean: fakeroot debian/rules clean.

   2. Run the maintscripts/maint-startnewrelease script from kteam-tools.

   3. Use git-rebase to reorder the commits and place the 'Start new release' before any other updates on master-next. Run:

        git rebase -i origin/master

      Move the 'Start new release' commit from the bottom of the list of commits to the top, then save the file and exit your editor.
3. Clean

    fakeroot debian/rules clean

4. Update the changelog (and possibly the debian.master/reconstruct and debian/source/options files) to include all the added commits by running:

    fakeroot debian/rules insertchanges

5. Add the tracking bug using the tools from kteam tools:

    create-release-tracker

   Warning: This will create a (visible) release tracking bug; use with care.

6. Review the changelog

7. Edit debian.master/changelog
   

   • replace UNRELEASED with <seriesname>

   • update the packagers line with your name and email address and the current time
     

8. Commit the changelog (and possibly the debian.master/reconstruct and debian/source/options files) with

    git add -u
    git commit -s -m "UBUNTU: Ubuntu-<changelog-version>"

   where <version> is copy and paste from head debian.master/changelog

9. Tag the release commit

    git tag -s -m Ubuntu-<changelog-version> Ubuntu-<changelog-version>

   where <version> is copy and paste from head debian.master/changelog. Note that in rare cases there may be commits on master-next that you choose to not release, in which case these commits will be on the master-next branch _after_ this most recent release tag Ubuntu-<version>.

10. Run the verify-release-ready script to make sure everything is OK. This will complain that the tag hasn't been pushed, but that's fine as you'll be pushing it shortly.
    

11. Test build it and do a quick test boot.
    

12. Push master-next and the new tag.

     git push --force-with-lease origin master-next <tagname>

13. This step onward should be done only after the kernel has been published to -updates.
    
    Switch to master branch. Make sure the local master branch is in sync with the origin/master

     git checkout -f master
     git fetch origin; git fetch origin master; git reset --hard FETCH_HEAD

    This resets the master branch to the the last commit in origin/master. Verify that HEAD is the same SHA1 as the prior release tag and that it is in common with master-next.

14. Reset master to the release tag. This must be a simple fast-forward operation, which can be enforced by performing a merge with the release tag using the --ff-only option.

     git merge --ff-only Ubuntu-<changelog-version>

    This will fail if the merge is not a fast-forward.

    If it's not then you can fix it and force commit or force tag your local tree, making sure it's right before you push to the master repo
    

15. Push your git branch to the origin master branch, explicitly including the tag

     git push origin master <tagname>