[6/8] dev-manual-common-tasks: Describe how to propose changes to stable branches

Submitted by Paul Barker on Nov. 11, 2020, 4:07 p.m. | Patch ID: 177930

Details

Message ID 20201111160800.5669-6-pbarker@konsulko.com
State New
Headers show

Commit Message

Paul Barker Nov. 11, 2020, 4:07 p.m.
The documentation on submitting changes to the project should cover the
ways in which the process differs for stable branches. These changes add
a brief description of the typical policy for handling changes to stable
branches and give some steps to follow when proposing changes to these
branches. The information is based on my personal experience and on the
existing content of the "How to submit a patch to OpenEmbedded" page on
the OE wiki.

Signed-off-by: Paul Barker <pbarker@konsulko.com>
---
 .../dev-manual/dev-manual-common-tasks.rst    | 55 +++++++++++++++++++
 1 file changed, 55 insertions(+)

Patch hide | download patch | download mbox

diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
index 0a3ab8241..e923ce834 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.rst
+++ b/documentation/dev-manual/dev-manual-common-tasks.rst
@@ -11005,6 +11005,61 @@  Lastly please ensure that you also test your revised changes. In particular
 please don't just edit the patch file written out by ``git format-patch`` and
 resend it.
 
+Submitting Changes to Stable Release Branches
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The process for proposing changes to a Yocto Project stable branch differs
+from the steps described above. Changes to a stable branch must address
+identified bugs or CVEs and should be made carefully in order to avoid the
+risk of introducing new bugs or breaking backwards compatibility. Typically
+bug fixes must already be accepted into the master branch before they can be
+backported to a stable branch unless the bug in question does not affect the
+master branch or the fix on the master branch is unsuitable for backporting.
+
+The list of stable branches along with the status and maintainer for each
+branch can be obtained from the `Releases wiki page <https://wiki.yoctoproject.org/wiki/Releases>`__.
+
+.. note::
+
+   Changes will not typically be accepted for branches which are marked as
+   End-Of-Life (EOL).
+
+With this in mind, the steps to submit a change for a stable branch are as
+follows:
+
+1. *Identify the bug or CVE to be fixed:* This information should be
+   collected so that it can be included in your submission.
+
+2. *Check if the fix is already present in the master branch:* This will
+   result in the most straightforward path into the stable branch for the
+   fix.
+
+   a. *If the fix is present in the master branch - Submit a backport request
+      by email:* You should send an email to the relevant stable branch
+      maintainer and the mailing list with details of the bug or CVE to be
+      fixed, the commit hash on the master branch that fixes the issue and
+      the stable branches which you would like this fix to be backported to.
+
+   b. *If the fix is not present in the master branch - Submit the fix to the
+      master branch first:* This will ensure that the fix passes through the
+      project's usual patch review and test processes before being accepted.
+      It will also ensure that bugs are not left unresolved in the master
+      branch itself. Once the fix is accepted in the master branch a backport
+      request can be submitted as above.
+
+   c. *If the fix is unsuitable for the master branch - Submit a patch
+      directly for the stable branch:* This method should be considered as a
+      last resort. It is typically necessary when the master branch is using
+      a newer version of the software which includes an upstream fix for the
+      issue or when the issue has been fixed on the master branch in a way
+      that introduces backwards incompatible changes. In this case follow the
+      steps in :ref:`preparing-changes-for-submissions` and
+      :ref:`submitting-a-patch` but modify the subject header of your patch
+      email to include the name of the stable branch which you are
+      targetting. This can be done using the ``--subject-prefix`` argument to
+      ``git format-patch``, for example to submit a patch to the dunfell
+      branch use ``git format-patch --subject-prefix='dunfell][PATCH' ...``.
+
 Working With Licenses
 =====================
 

Comments

Quentin Schulz Nov. 11, 2020, 4:39 p.m.
Hi Paul,

On Wed, Nov 11, 2020 at 04:07:58PM +0000, Paul Barker wrote:
> The documentation on submitting changes to the project should cover the
> ways in which the process differs for stable branches. These changes add
> a brief description of the typical policy for handling changes to stable
> branches and give some steps to follow when proposing changes to these
> branches. The information is based on my personal experience and on the
> existing content of the "How to submit a patch to OpenEmbedded" page on
> the OE wiki.
> 
> Signed-off-by: Paul Barker <pbarker@konsulko.com>
> ---
>  .../dev-manual/dev-manual-common-tasks.rst    | 55 +++++++++++++++++++
>  1 file changed, 55 insertions(+)
> 
> diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
> index 0a3ab8241..e923ce834 100644
> --- a/documentation/dev-manual/dev-manual-common-tasks.rst
> +++ b/documentation/dev-manual/dev-manual-common-tasks.rst
> @@ -11005,6 +11005,61 @@ Lastly please ensure that you also test your revised changes. In particular
>  please don't just edit the patch file written out by ``git format-patch`` and
>  resend it.
>  
> +Submitting Changes to Stable Release Branches
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The process for proposing changes to a Yocto Project stable branch differs
> +from the steps described above. Changes to a stable branch must address
> +identified bugs or CVEs and should be made carefully in order to avoid the
> +risk of introducing new bugs or breaking backwards compatibility. Typically
> +bug fixes must already be accepted into the master branch before they can be
> +backported to a stable branch unless the bug in question does not affect the
> +master branch or the fix on the master branch is unsuitable for backporting.
> +
> +The list of stable branches along with the status and maintainer for each
> +branch can be obtained from the `Releases wiki page <https://wiki.yoctoproject.org/wiki/Releases>`__.
> +

:yocto_wiki:`Releases wiki page </wiki/Releases>`

> +.. note::
> +
> +   Changes will not typically be accepted for branches which are marked as
> +   End-Of-Life (EOL).
> +
> +With this in mind, the steps to submit a change for a stable branch are as
> +follows:
> +
> +1. *Identify the bug or CVE to be fixed:* This information should be
> +   collected so that it can be included in your submission.
> +
> +2. *Check if the fix is already present in the master branch:* This will
> +   result in the most straightforward path into the stable branch for the
> +   fix.
> +
> +   a. *If the fix is present in the master branch - Submit a backport request
> +      by email:* You should send an email to the relevant stable branch
> +      maintainer and the mailing list with details of the bug or CVE to be
> +      fixed, the commit hash on the master branch that fixes the issue and
> +      the stable branches which you would like this fix to be backported to.
> +
> +   b. *If the fix is not present in the master branch - Submit the fix to the
> +      master branch first:* This will ensure that the fix passes through the
> +      project's usual patch review and test processes before being accepted.
> +      It will also ensure that bugs are not left unresolved in the master
> +      branch itself. Once the fix is accepted in the master branch a backport
> +      request can be submitted as above.
> +
> +   c. *If the fix is unsuitable for the master branch - Submit a patch
> +      directly for the stable branch:* This method should be considered as a
> +      last resort. It is typically necessary when the master branch is using
> +      a newer version of the software which includes an upstream fix for the
> +      issue or when the issue has been fixed on the master branch in a way
> +      that introduces backwards incompatible changes. In this case follow the
> +      steps in :ref:`preparing-changes-for-submissions` and
> +      :ref:`submitting-a-patch` but modify the subject header of your patch
> +      email to include the name of the stable branch which you are
> +      targetting. This can be done using the ``--subject-prefix`` argument to
> +      ``git format-patch``, for example to submit a patch to the dunfell
> +      branch use ``git format-patch --subject-prefix='dunfell][PATCH' ...``.

s/dunfell/&DISTRO_NAME_NO_CAP_MINUS_ONE;/g ?

Thanks,
Quentin
-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.
View/Reply Online (#598): https://lists.yoctoproject.org/g/docs/message/598
Mute This Topic: https://lists.yoctoproject.org/mt/78185917/3617530
Group Owner: docs+owner@lists.yoctoproject.org
Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [oe-patchwork@oe-patch.openembedded.org]
-=-=-=-=-=-=-=-=-=-=-=-
Nicolas Dechesne Nov. 11, 2020, 5:31 p.m.
On Wed, Nov 11, 2020 at 5:39 PM Quentin Schulz
<quentin.schulz@streamunlimited.com> wrote:
>
> Hi Paul,
>
> On Wed, Nov 11, 2020 at 04:07:58PM +0000, Paul Barker wrote:
> > The documentation on submitting changes to the project should cover the
> > ways in which the process differs for stable branches. These changes add
> > a brief description of the typical policy for handling changes to stable
> > branches and give some steps to follow when proposing changes to these
> > branches. The information is based on my personal experience and on the
> > existing content of the "How to submit a patch to OpenEmbedded" page on
> > the OE wiki.
> >
> > Signed-off-by: Paul Barker <pbarker@konsulko.com>
> > ---
> >  .../dev-manual/dev-manual-common-tasks.rst    | 55 +++++++++++++++++++
> >  1 file changed, 55 insertions(+)
> >
> > diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
> > index 0a3ab8241..e923ce834 100644
> > --- a/documentation/dev-manual/dev-manual-common-tasks.rst
> > +++ b/documentation/dev-manual/dev-manual-common-tasks.rst
> > @@ -11005,6 +11005,61 @@ Lastly please ensure that you also test your revised changes. In particular
> >  please don't just edit the patch file written out by ``git format-patch`` and
> >  resend it.
> >
> > +Submitting Changes to Stable Release Branches
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +The process for proposing changes to a Yocto Project stable branch differs
> > +from the steps described above. Changes to a stable branch must address
> > +identified bugs or CVEs and should be made carefully in order to avoid the
> > +risk of introducing new bugs or breaking backwards compatibility. Typically
> > +bug fixes must already be accepted into the master branch before they can be
> > +backported to a stable branch unless the bug in question does not affect the
> > +master branch or the fix on the master branch is unsuitable for backporting.
> > +
> > +The list of stable branches along with the status and maintainer for each
> > +branch can be obtained from the `Releases wiki page <https://wiki.yoctoproject.org/wiki/Releases>`__.
> > +
>
> :yocto_wiki:`Releases wiki page </wiki/Releases>`
>
> > +.. note::
> > +
> > +   Changes will not typically be accepted for branches which are marked as
> > +   End-Of-Life (EOL).
> > +
> > +With this in mind, the steps to submit a change for a stable branch are as
> > +follows:
> > +
> > +1. *Identify the bug or CVE to be fixed:* This information should be
> > +   collected so that it can be included in your submission.
> > +
> > +2. *Check if the fix is already present in the master branch:* This will
> > +   result in the most straightforward path into the stable branch for the
> > +   fix.
> > +
> > +   a. *If the fix is present in the master branch - Submit a backport request
> > +      by email:* You should send an email to the relevant stable branch
> > +      maintainer and the mailing list with details of the bug or CVE to be
> > +      fixed, the commit hash on the master branch that fixes the issue and
> > +      the stable branches which you would like this fix to be backported to.
> > +
> > +   b. *If the fix is not present in the master branch - Submit the fix to the
> > +      master branch first:* This will ensure that the fix passes through the
> > +      project's usual patch review and test processes before being accepted.
> > +      It will also ensure that bugs are not left unresolved in the master
> > +      branch itself. Once the fix is accepted in the master branch a backport
> > +      request can be submitted as above.
> > +
> > +   c. *If the fix is unsuitable for the master branch - Submit a patch
> > +      directly for the stable branch:* This method should be considered as a
> > +      last resort. It is typically necessary when the master branch is using
> > +      a newer version of the software which includes an upstream fix for the
> > +      issue or when the issue has been fixed on the master branch in a way
> > +      that introduces backwards incompatible changes. In this case follow the
> > +      steps in :ref:`preparing-changes-for-submissions` and
> > +      :ref:`submitting-a-patch` but modify the subject header of your patch
> > +      email to include the name of the stable branch which you are
> > +      targetting. This can be done using the ``--subject-prefix`` argument to
> > +      ``git format-patch``, for example to submit a patch to the dunfell
> > +      branch use ``git format-patch --subject-prefix='dunfell][PATCH' ...``.
>
> s/dunfell/&DISTRO_NAME_NO_CAP_MINUS_ONE;/g ?

ouch.. that makes me realize we didn't update them in gatesgarth
branch yet..  and we should.. will send something..

>
> Thanks,
> Quentin
>
> 
>
-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.
View/Reply Online (#603): https://lists.yoctoproject.org/g/docs/message/603
Mute This Topic: https://lists.yoctoproject.org/mt/78185917/3617530
Group Owner: docs+owner@lists.yoctoproject.org
Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [oe-patchwork@oe-patch.openembedded.org]
-=-=-=-=-=-=-=-=-=-=-=-