StablePatchFormat

Stable Patch Format

Destination

Stable patches must be sent to: kernel-team@lists.ubuntu.com

Important: please subscribe here to the mailing list before sending your first patch. Messages from non-subscribers will be sent to a queue waiting for an admin approval. You can also manage your subscription and access the mailing list archive on https://lists.ubuntu.com/mailman/listinfo/kernel-team.

Subject Line

  1. Every patch submitted to a stable kernel must have have its subject line starting with "[SRU]" followed by the release name against which the patch is targeted. That release name must be enclosed in "[ ]" brackets and can be abbreviated using the first letter of the release name (e.g. "B" for "Bionic"). If a patch is to be applied to multiple releases a list of release names can be provided.

    Examples: 

     [SRU][Focal][PULL] Focal update: v5.4.56 upstream stable release
 [SRU][B][F][PATCH 1/1] KVM: fix overflow of zero page refcount with ksm running

    Notes:
    - If the patch has to be applied to multiple releases and the subject becomes to hard to follows, you can feel free to drop some of the brackets. For example 

     [SRU][B][F][J][PATCH 0/1] UBUNTU: [Config]: Add support for modifying LDT
 can easily become:
 [SRU][B,F,J][PATCH 0/1] UBUNTU: [Config]: Add support for modifying LDT
    - If the patch has to be applied to a specific derivative for multiple release this is the recommended format: 
     [SRU][B,F:linux-kvm] [PATCH 0/1] UBUNTU: [Config] kvm: Add support for modifying LDT

  2. If the patch requested doesn't come from the mainline tree it must contain one of the following on the Subject line after the release name string described previously:

    Descriptor

    Meaning

    UBUNTU:

    This is a patch to the Ubuntu Packaging, including the contents of the various debian* directories (where not covered by a more specific categorisation)

    UBUNTU: [Config]

    This is an update to the kernel configuration as recorded in the debian.<branch>/config directory. Please check debian.master/config/README.rst or here for more information about the config format.

    UBUNTU: ubuntu:

    This is an update to an Ubuntu specific driver in the ubuntu/ directory.

    UBUNTU: SAUCE:

    This is a patch to the kernel code that has not been applied on mainline (Linus' tree). This category covers the following cases:
    1. The submitter has either authored the patch or obtained the patch from a non-upstream source.
    2. The patch has been applied to an upstream tree but not yet merged on mainline.
    3. The patch is never expected to be submitted upstream but is of enough value for Ubuntu to carry it in our tree.
    4. The patch has been submitted to upstream but is of enough value for Ubuntu to carry it in our tree regardless of upstream acceptance.

    UBUNTU: [Debian]

    This patch changes the debian rules files (debian/rules, debian*/rules.d/* and possibly debian*/control and debian*/control.d/*).

    Example: 

     [SRU][FOCAL][PATCH 2/2] UBUNTU: SAUCE: shiftfs: prevent ESTALE for LOOKUP_JUMP lookups

Comment Body

  1. Every patch which is associated with a launchpad bug must have a link to the bug in the commit's comment section in the form of a "BugLink" block. A "BugLink" block must immediately follow the subject line and be the first text in the body of the commit comment. A "BugLink" block consists of:

    1. A blank line.

    2. One or more lines containing "BugLink:" and a url to the launchpad bug. That url must be of the format: "https://bugs.launchpad.net/bugs/<bug-id>" where <bug-id> is the bug number of the associated Launchpad bug.

    3. Another blank line.

    Every stable patch must have an associated Launchpad bug for tracking by the kernel stable and SRU teams. Exceptions are patches for CVE fixes (see below).

    Example: 

     1: Subject: [PATCH 1/1][SRU][B] UBUNTU: SAUCE: platform/x86: dell-uart-backlight: add get_display_mode command
 2:
 3: BugLink: https://bugs.launchpad.net/bugs/1865402
 4: BugLink: https://bugs.launchpad.net/bugs/1234567
 5:

  2. Every patch must have a "Signed-off-by" line for the person that is submitting the patch. This "Signed-off-by" line must follow all other provenance lines and should be the last line in the commit comment.

    Example: 

     Signed-off-by: Jesse Barnes <jbarnes@virtuousgeek.org>
 Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
 (backported from commit 5620ae29f1eabe655f44335231b580a78c8364ea)
 Signed-off-by: Manoj Iyer <manoj.iyer@canonical.com>

  3. Where acks are needed they should be placed in the provenance block. Every patch against Development releases following Kernel freeze and all patches against released kernels must have two "Acked-by" replies by "senior" members of the Ubuntu Kernel Team.

    Example: 

     Signed-off-by: Adam Jackson <ajax@redhat.com>
 Signed-off-by: Eric Anholt <eric@anholt.net>
 Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
 (cherry picked from commit d4e0018e3e4dd685af25d300fd26a0d5a984482e 2.6.34.y)
 Signed-off-by: Manoj Iyer <manoj.iyer@canonical.com>
 Acked-by: Tim Gardner <tim.gardner@canonical.com>
 Acked-by: Brad Figg <brad.figg@canonical.com>
 Acked-by: Steve Conklin <sconklin@canonical.com>

  4. Every patch must display the provenance of the patch. We want to preserve where the patch came from, who signed off on it, who ack'd it, whether it was cherry-picked from upstream and applied cleanly or not and who finally applied it to an official Ubuntu source tree. Cherry-picked from vs backported from:

    If the patch required changes (it did not apply cleanly), 'backported-from <sha1>' has to be used i.e 

     (backported from commit <sha1> <upstream repo name>)
    Please note that the opening and closing parenthesis are required. There must be a brief explanation immediately after the "(backported from ...)" block, between square brackets, with the name of the person who introduced the change: 
     (backported from commit <sha1> <upstream repo name>)
 [roxanan: Had to adjust the context due to missing commit <sha1>]

    If the patch is a simple cherry-pick from an upstream repo and it applies cleanly, that must also be spelled out in the provenance section in the form by using 'cherry-picked from': 

     (cherry picked from commit <sha1> <upstream repo name>)
    The opening and closing parenthesis are required here as well.

    Note: "<upstream repo name>" can be omitted if the patch comes from the mainline tree.

    Example: 

     Signed-off-by: Adam Jackson <ajax@redhat.com>
 Signed-off-by: Eric Anholt <eric@anholt.net>
 Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
 (cherry picked from commit d4e0018e3e4dd685af25d300fd26a0d5a984482e 2.6.34.y)
 Signed-off-by: Manoj Iyer <manoj.iyer@canonical.com>
 Acked-by: Tim Gardner <tim.gardner@canonical.com>
 Acked-by: Brad Figg <brad.figg@canonical.com>
 Acked-by: Steve Conklin <sconklin@canonical.com>

  5. Every CVE patch must contain a line at the beginning of the commit message that specifies the CVE number(s) related to the patch. This must be the first part of the body of the comment. There is the comment subject line, a blank line, the CVE number, a blank line and then the rest of the comment body. A "BugLink" is optional for CVE patches.

    Example: 

    Subject: [SRU B/D] UBUNTU: SAUCE: nbd_genl_status: null check for nla_nest_start

From: Navid Emamdoost <navid.emamdoost@gmail.com>

CVE-2019-16089

nla_nest_start may fail and return NULL. The check is inserted, and
errno is selected based on other call sites within the same source code.
Update: removed extra new line.
v3 Update: added release reply, thanks to Michal Kubecek for pointing
out.
...

Patch Series

  1. Every patch submitted to a stable kernel must be sent in a patch series with a cover letter, even if the patch series contains a single patch.

  2. The cover letter must contain the "BugLink" or the CVE number like the patch(es) itself.

  3. The cover letter must contain the SRU justification from the launchpad bug or the CVE fix. See KernelTeam/KernelUpdates.

  4. All the emails in the patch series must be numbered (e.g. "[PATCH 0/3]", "[PATCH 1/3]", etc.) and all the patches sent in reply to the cover letter (PATCH 0/N). See the option "--no-chain-reply-to" from git-send-email(1).

Pull Request

When the patch series is relatively large (e.g. more than 5 patches), please consider sending a git pull request instead of a patch series. A pull request is usually easier to review than a large number of patches in the same email thread. For a pull request, please follow these guidelines:

  1. Include the git pull request information in the cover letter email, which should still contain the information requested above.
  2. Please make sure the git repository is public.
  3. Add a "[PULL]" tag to the subject line of the cover letter instead of "[PATCH X/N]".
  4. The body of the commits should follow the same rules as for a patch series.

  5. The format of the title of the commits contained in the pull request should be the same as for the patch series, except for the tags at the beginning of the subject enclosed in "[]" brackets which would be removed by git am on application.

Complete Example

Cover letter
  • Subject: [SRU][F][PATCH 0/1] s390/cpum_cf: Add new extended counters for IBM z15 (LP: 1881096)
From: frank.heimes@canonical.com
Date: 24.06.20, 22:11
To: kernel-team@lists.ubuntu.com

Buglink: https://bugs.launchpad.net/bugs/1881096

SRU Justification:

[Impact]

* With perf from Ubuntu 20.04 on IBM z15 hardware, some counters reported with lscpumf are not usable with 'perf stat -e'.
[...]

[Fix]

* d68d5d51dc898895b4e15bea52e5668ca9e76180 d68d5d51dc898895b "s390/cpum_cf: Add new extended counters for IBM z15"

[Test Plan]

* Requires the fix/patch of the perf tool, as mentioned in the bug, too.
[...]

[Where problems could occur]

* The regression can be considered as low, since:
[...]

[Other Info]

* This requires a patch to be included into the perf itself, too - please see bug description for more details.
[...]

Patch 1/1
  • Subject: [SRU][F][PATCH 1/1] s390/cpum_cf: Add new extended counters for IBM z15
From: frank.heimes@canonical.com
Date: 24.06.20, 22:11
To: kernel-team@lists.ubuntu.com

From: Thomas Richter <tmricht@linux.ibm.com>

BugLink: https://bugs.launchpad.net/bugs/1881096

Add CPU measurement counter facility event description for IBM z15.

Signed-off-by: Thomas Richter <tmricht@linux.ibm.com>
Reviewed-by: Sumanth Korikkar <sumanthk@linux.ibm.com>
Signed-off-by: Vasily Gorbik <gor@linux.ibm.com>
(cherry picked from commit d68d5d51dc898895b4e15bea52e5668ca9e76180)
Signed-off-by: Frank Heimes <frank.heimes@canonical.com>

[...]

Tips

1. When sending patches with git-send-email, use the option "--suppress-cc=all" in order to prevent adding the original author of the patch and other people from the provenance block as CC.

See Also

  • Kernel Updates

    Shows the SRU Justification format to be added to a bug.

Kernel/Dev/StablePatchFormat (last edited 2024-02-22 15:53:06 by roxanan)