||<tablestyle="float:right; font-size: 0.9em; width:40%; background:#F1F1ED; margin: 0 0 1em 1em;" style="padding:0.5em;"><<TableOfContents>>||

== Overview ==

It was agreed that for the life time of a LTS release and 4 months after a non-LTS release we will follow the changes in the related upstream stable tree as closely as possible. To prevent surprises, have a better feeling on what comes down that way and to follow SRU policy, every single patch needs to be reviewed and the whole set needs to get ACKed by at least two senior kernel team members.

 * Every upstream stable release gets assigned to a single bug report.
 * Patches already carried get reverted and replaced by the upstream stable version unless
   * they were part of a security update
   * they were part of complete subsystem update
   * they cannot be reverted because the same area has been modified by subsequent changes
 * Including an upstream stable update requires the package to stay at least 14 days in proposed.

== Stable Patches ==
Greg Kroah-Hartman (Greg KH) is the upstream, stable tree maintainer.

There are three mailing lists involved in the upstream process:

 * stable@kernel.org is the target for requests to stable. This currently is more or less an alias for Greg.
 * [[http://vger.kernel.org/vger-lists.html#stable-commits|stable-commmits@vger.kernel.org]] will receive an email for each patch that gets added to one of the upstream stable trees.
 * [[http://linux.kernel.org/mailman/listinfo/stable-review|stable-review@kernel.org]] will receive emails whenever a review cycle starts together with all patches contained in that cycle.

=== Pre-release Patch Flow ===
As patches are queued up to be applied to the upstream repository they are announced on
the ''Stable Commits'' mailing list. It's not a bad idea to subscribe to this mailing list
to get an idea of some of the patches that will be coming in the next stable release. To
subscribe / unsubscribe or get a link to the archives visit: {{{http://vger.kernel.org/vger-lists.html#stable-commits.}}}

These pre-release patches are also queued up in Greg HK's stable repository. That repository
can be found at:

{{{
git://git.kernel.org/pub/scm/linux/kernel/git/stable/stable-queue.git
}}}

This contains directories for each currently maintained tree. The specific names change depending on the state of the review cycle. Patch series are kept in quilt format (meaning there is a series file which contains the sequence in which the patches have to be applied).

 * queue-2.6.x contains patches that are queued up for the next review cycle.
 * The queue-2.6.x directories will (in theory) get renamed to review-2.6.x as soon as the review cycle starts.
 * After release, the review-2.6.x will be moved into release/2.6.x.y
 * There are some other directories as well which use is unclear. They might either be abandoned or seldomly used.

=== Release Announcement ===
Greg KH announces the release of stable patches on the ''Linux Kernel'' mailing list (lkml). 
To subscribe, unsubscribe or get a link to the archives for this mailing list visit: 
{{{http://vger.kernel.org/vger-lists.html#linux-kernel}}}

=== Repositories ===
Greg KH's announcement email contains the path to the git repository for the kernel tree with
the patches applied. There is a separate git repository for each release kernel version.

The numbering is based on the main kernel version and adds a subversion number for each stable release.

{{{
git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-2.6.x.y.git
}}}


== Ubuntu Kernel Team Tools ==
<<Include(Kernel/kteam-tools, , from="^=== .* ===$")>>


== SRU Tasks ==

=== Create the Tracking Bug ===

'''Title''': [<series>] Update to 2.6.x.y Stable Kernel

'''Bug Description:'''
{{{
SRU Justification

Impact: The upstream process for stable tree updates is quite similar in scope to the Ubuntu SRU process, e.g., each patch has to demonstrably fix a bug, and each patch is vetted by upstream by originating either directly from Linus' tree or in a minimally backported form of that patch. The 2.6.x.y upstream stable patch set is now available. It should be included in the Ubuntu kernel as well.

http://kernel.org/pub/linux/kernel/v2.6/ChangeLog-2.6.x.y
http://kernel.org/pub/linux/kernel/v2.6/patch-2.6.x.y.bz2

TEST CASE: TBD

==========

The following # patches have been in 2.6.x.y:
}}}

Additional note for ''Lucid'' (for the DRM stack from 2.6.33):
{{{
Due to the fact that we are carrying the DRM backport from 2.6.33, all patches affecting DRM have been dropped from the 2.6.32.12 port and picked from 2.6.33.3 instead.

http://kernel.org/pub/linux/kernel/v2.6/ChangeLog-2.6.33.y
http://kernel.org/pub/linux/kernel/v2.6/patch-2.6.33.y.bz2

The following # patches have been in 2.6.33.y:
}}}

=== Create a Review Repository ===
You will need to create a respositry where the patches will be applied and made available to other developers
for review. This will be the repository that will be pointed to in the git pull-request email that
is sent out.

'''Lucid Example:'''

A fresh clone of the current stable git repo is usually best. This makes sure the patches are being
applied to the latest stable code and ensures there are no personal patches mistakenly added to
the pull request.
{{{
git clone git://kernel.ubuntu.com/ubuntu/ubuntu-lucid.git
}}}

It is also a good idea to apply the patches to a branch.
{{{
cd ubuntu-lucid
git co -b lucid-stable-update
}}}

=== Issue a Pull Request ===
In order for any SRU patches to be accepted and applied to the master stable tree they must be
peer reviewed. To request a peer review of the patches an email, in the form of a pull request
must be sent to the Ubuntu Kernel Team mailing list ( {{{kernel-team@lists.ubuntu.com}}} ).

{{{
To: kernel-team@lists.ubuntu.com
Subject: [<series>][pull request] Update to 2.6.<x>.<y+1> Stable Kernel

Hi All,

http://bugs.launchpad.net/bugs/<bug number>

The 2.6.<x>.<y+1> stable kernel has recently been released.

http://kernel.org/pub/linux/kernel/v2.6/ChangeLog-2.6.<x>.<y+1>
http://kernel.org/pub/linux/kernel/v2.6/patch-2.6.32.<x>.bz2

The 2.6.<x>.<y+1> upstream stable kernel brings in # patches [(DRM excluded).
As we carry the DRM stack from 2.6.33, all patches that affect DRM have been
dropped and replaced by DRM patches from 2.6.33.<z+1> (# patches).]

The upstream process for stable tree updates is quite similar in scope to the
Ubuntu SRU process. e.g: each patch demonstrably fixes a bug and is vetted by
upstream either by originating directly from Linus' tree or by being minimally
backported from some patch in Linus' tree.

TEST CASE: TBD

<put description of reverted, skipped patches here and why)>

I am attaching the review and I have pushed a preview tree to

git://kernel.ubuntu.com/<user>/ubuntu-<series>.git stable

http://kernel.ubuntu.com/git?p=<user>/ubuntu-<series>.git;a=shortlog;h=refs/heads/stable
}}}

=== Prepare for Review ===
There are some usefull tools in the Ubuntu Kernel Teams kteam-tools. One that is very
helpful in reviewing patches is {{{maint-do-review}}}. This tool will be used in the 
following example. See the previous '''Ubuntu Kernel Team Tools''' section on where to 
find the tools.

=== Perform the Review ===

{{{
cd <work tree to review>
maint-do-review <text file> <git range>
}}}

This will

 * create the text file if it does not exist, or make a backup copy if it does
 * checks all subject lines in the range given and either adds the commit in the state "NEW" or adds a comment to an existing entry if it is not (anymore) contained in the range.
 * opens the text file using gvim
 * offer to open the next patch that is still in state NEW with git-compare

'''Example Review:'''

Upstream review can be started as soon as there is a new batch of patches committed to stable-queue. The maint-do-review tool helps to keep track of changes going on.
The following example assumes there is a working tree of stable-queue and the stable tree to follow and the stable tree has a local branch called ''next'' as a staging area. In ranges ''y'' stands for the last released version. ''y+1'' would be the next to come.

{{{
cd <work tree for 2.6.x.y>
git checkout -f next
git fetch
git reset --hard origin/master
git quiltimport --patches=<stable-queue>/(queue|review)-2.6.x.y
maint-do-review ../stable-2.6.x.y+1.txt v2.6.x.y..
}}}

=== Submit Review Comments ===
One of the by-products of the above review of patches is the {{{../stable-2.6.x.y+1.txt}}} file.
That file should be added, inline, to a reply to the pull request email, preceeded by either an
ACK or NAK of the patches.

=== Apply Ack'd Patches to Master Repository ===

{i} It is a good idea to have a new release opened and pushed on the master branch. That way it is simpler to do test builds while it is possible to either simply merge the work branch or collect patches using ''git merge-base''.

{i} Bug links to the tracking bug are added later to catch reverts as well.

First step is to create patches from the stable tree:
{{{
git format-patch v2.6.x.y..
}}}

Then, in the working tree for the release, create a ''stable'' branch (the name does not really matter) from the ''HEAD'' of master.

{{{
git checkout -f stable
git reset --hard origin/master
git am <stable tree>/*.patch
}}}

<!> Using ''git am --abort'' will revert back to the state when ''git am'' was started!

That said, when a patch fails to apply, the first thing to check is whether it is in the tree already. If it is, but was either part of a security release or is impossible or very hard to revert (because it was part of a combined patch or there are changes on top of it), then it us ok to skip it with ''git am --skip''. However

 * Make sure the changes of the patch are in the code base.
 * Document the exception in the tracking bug.

If the patch can be reverted, use git to revert it and apply the patch manually.
{{{
git revert -s -e <sha1>
patch -p1 <.git/rebase-apply/patch
git add <changed or added files>
git am --resolved
}}}

In the commit message of the revert, the reason for the revert should be stated. Something along the line "This patch has been reverted to be replaced by an upstream stable patch from 2.6.x.y".

Patches that do not aply for other reasons need to be massaged until they apply and then, after adding the changed files, applied with ''git am --resolved''.

{i} Using ''patch -p1 <.git/rebase-apply/patch'' and then handle the real failures helps to avoid unnecessary work.

When all patches have been handled, the branch can be pushed to a public personal repo to help others on the review.

=== OTHER ===

==== maint-modify-patch ====

Also in ''kteam-tools'', used to mass-add bug links, acks and signed-off-by.

The list of patches can be generated by:
{{{
git log --pretty='* %s' --reverse v2.6.x.y..
}}}

{i} There was something I forgot...

==== If an ABI bump is required ====

If you find when building your test branch that an ABI bump is required, bump the ABI by editing debian.master/changelog and increasing the ABI, then commit that change using the bumpabi commit template.

For example, if the top of the changelog looked like this:
{{{
linux (2.6.32-23.38) UNRELEASED; urgency=low

  CHANGELOG: Do not edit directly. Autogenerated at release.
  CHANGELOG: Use the printchanges target to see the curent changes.
  CHANGELOG: Use the insertchanges target to create the final log.

 -- Stefan Bader <stefan.bader@canonical.com>  Tue, 15 Jun 2010 10:02:32 +0100
}}}

Then you would change it to this:
{{{
linux (2.6.32-24.38) UNRELEASED; urgency=low

  CHANGELOG: Do not edit directly. Autogenerated at release.
  CHANGELOG: Use the printchanges target to see the curent changes.
  CHANGELOG: Use the insertchanges target to create the final log.

 -- Stefan Bader <stefan.bader@canonical.com>  Tue, 15 Jun 2010 10:02:32 +0100
}}}

You must also make the ABI bump to the -meta and -lbm trees. For -meta, if the new release is already open and the changelog looks like the examples above, you just edit the versions like shown above. If the release is not open, you have to run "fdr startnewrelease" first. For -lbm, just change the version, and commit it with a commit message like the previous ones.

==== Applying the SRU ====

On the stable branch (and making sure that no other patches are in that directory):
{{{
git format-patch $(git merge-base origin/master stable)
maint-modify-patch -b <bug number> *.patch
maint-modify-patch -a<ack1> *.patch
maint-modify-patch -a<ack2> *.patch
maint-modify-patch -s *.patch
git checkout master
git am *.patch
}}}