Ubuntu code patches guideline
=============================

Code patches applied to an Ubuntu kernel fall into two categories:
``cherry-pick/backport of upstream patches``, or custom code changes that are not
upstream yet / never will (we call the latter ``UBUNTU SAUCE`` patches).

For a detailed description on how to format patches before submission, see this
`guideline document`_, while here is a quick (and far from complete)
introduction.

Upstream cherry-picks/backports
-------------------------------

When cherry-picking an upstream patch, always use:

.. code-block:: shell

       $ git cherry-pick -sx $PATCHSHA

and the resulting commit should like this:

.. code-block:: shell

       commit c057fb5db41cafcc2ed8a72ce81627159316c2ba
       Author: Stefan Binding <sbinding@opensource.cirrus.com>
       Date:   Thu Jun 30 01:23:35 2022 +0100
       
       ALSA: hda: cs35l41: Add module parameter to control firmware load
           
       BugLink: https://bugs.launchpad.net/bugs/1995957
           
       By default, the driver will automatically load DSP firmware
       for the amps, if available. Adding this option allows the
       autoload to be optional, which allows for different configurations.
           
       Signed-off-by: Stefan Binding <sbinding@opensource.cirrus.com>
       Signed-off-by: Vitaly Rodionov <vitalyr@opensource.cirrus.com>
       Signed-off-by: Takashi Iwai <tiwai@suse.de>
       (cherry picked from commit 622f21994506e1dac7b8e4e362c8951426e032c5)
       Signed-off-by: Kai-Heng Feng <kai.heng.feng@canonical.com>

pay particular attention to:

The ``BugLink`` line (must be manually added) points to a valid bug on
Launchpad. Bugs on Launchpad contain a description of the issue, the reason to
apply the submitted code, regression potential, etc - see also `SRU
template`_ and this `example`_.

The last ``Signed-off-by`` line (automatically added by ``git cherry-pick -s``)
defines the submitter of the change (not necessarily the author of the change, but whoever proposed the change to be included in the Ubuntu kernel). 

The ``cherry picked`` line (automatically added by git ``cherry-pick -x``)
contains the original SHA of the upstream commit. In case the upstream source is
linux-next, explicit it:

.. code-block:: shell

       (cherry picked from commit 622f21994506e1dac7b8e4e362c8951426e032c5 linux-next)

And in case the provenance is anything but Linus tree or linux-next, explicit the source git tree in full:

.. code-block:: shell

       (cherry picked from commit 622f21994506e1dac7b8e4e362c8951426e032c5 git://git.kernel.org/pub/scm/linux/kernel/git/broonie/sound.git)

In case of a backport from a more recent kernel than the target, state it:

.. code-block:: shell

       (backported from commit 622f21994506e1dac7b8e4e362c8951426e032c5 git://git.kernel.org/pub/scm/linux/kernel/git/broonie/sound.git)

The UBUNTU SAUCE
----------------

SAUCE patches follow the above rules, the main difference is in the subject line:

.. code-block:: shell

       commit dc3163b33449199651660b6121571ef5081d79a3
       Author: Wen Gong <quic_wgong@quicinc.com>
       Date:   Fri Oct 28 13:07:06 2022 +0800
       UBUNTU: SAUCE: wifi: ath11k: avoid deadlock during regulatory update in ath11k_regd_update()
       
           
       BugLink: https://bugs.launchpad.net/bugs/1995041
           
       ...
       
       (cherry picked from commit d99884ad9e3673a12879bc2830f6e5a66cccbd78 https://git.kernel.org/pub/scm/linux/kernel/git/kvalo/ath.git master)
       
       Signed-off-by: Aaron Ma <aaron.ma@canonical.com>

where the prefix ``UBUNTU SAUCE`` is added in the patch subject.

Submitted patches that don’t follow these rules will likely be rejected.

.. _guideline document: https://wiki.ubuntu.com/Kernel/Dev/StablePatchFormat
.. _SRU template: https://wiki.ubuntu.com/StableReleaseUpdates?action=show&redirect=SRU#SRU_Bug_Template
.. _example: https://bugs.launchpad.net/ubuntu/+source/linux/+bug/1995957