[PATCH 1/8] dev-manual-common-tasks: Fix refs to testing branches

[PATCH 1/8] dev-manual-common-tasks: Fix refs to testing branches

[Paul Barker]

After discussions on IRC with Ross we concluded that the `ross/mut`
branch shouldn't really be listed in the docs as it's more of a personal
test branch. Instead we should list the -next branches for
openembedded-core and poky.

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

diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
index 27aacde60..698b27377 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.rst
+++ b/documentation/dev-manual/dev-manual-common-tasks.rst
@@ -10665,18 +10665,29 @@ to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a
 section in the Yocto Project Overview and Concepts Manual for additional
 concepts on working in the Yocto Project development environment.
 
-Two commonly used testing repositories exist for OpenEmbedded-Core:
-
--  *"ross/mut" branch:* The "mut" (master-under-test) tree exists in the
-   ``poky-contrib`` repository in the
-   :yocto_git:`Yocto Project source repositories <>`.
-
--  *"master-next" branch:* This branch is part of the main "poky"
-   repository in the Yocto Project source repositories.
-
-Maintainers use these branches to test submissions prior to merging
-patches. Thus, you can get an idea of the status of a patch based on
-whether the patch has been merged into one of these branches.
+Maintainers commonly use ``-next`` branches to test submissions prior to
+merging patches. Thus, you can get an idea of the status of a patch based on
+whether the patch has been merged into one of these branches. The commonly
+used testing branches for OpenEmbedded-Core are as follows:
+
+-  *openembedded-core "master-next" branch:* This branch is part of the
+   `openembedded-core <https://git.openembedded.org/openembedded-core/>`__
+   repository on git.openembedded.org and contains proposed changes to the
+   core metadata.
+
+-  *poky "master-next" branch:* This branch is part of the
+   `poky <https://git.yoctoproject.org/cgit/cgit.cgi/poky/>`__
+   repository on git.yoctoproject.org and combines proposed changes to
+   bitbake, the core metadata and the poky distro.
+
+Similarly, stable branches maintained by the project may have corresponding
+``-next`` branches which collect proposed changes. For example,
+``dunfell-next`` and ``gatesgarth-next`` branches in both the
+"openembdedded-core" and "poky" repositories.
+
+Other layers may have similar testing branches but there is no formal
+requirement or standard for these so please check the documentation for the
+layers you are contributing to.
 
 .. note::
 
-- 
2.20.1

[PATCH 2/8] dev-manual-common-tasks: Update & move patchwork reference

[Paul Barker]

Add a link to our patchwork instance and note how submitted patches are
checked for common mistakes. This note is moved to the section on
submitting patches via email as that is the place where most users will
run into patchwork/patchtest.

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

diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
index 698b27377..2f28cce62 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.rst
+++ b/documentation/dev-manual/dev-manual-common-tasks.rst
@@ -10689,16 +10689,6 @@ Other layers may have similar testing branches but there is no formal
 requirement or standard for these so please check the documentation for the
 layers you are contributing to.
 
-.. note::
-
-   This system is imperfect and changes can sometimes get lost in the
-   flow. Asking about the status of a patch or change is reasonable if
-   the change has been idle for a while with no feedback. The Yocto
-   Project does have plans to use
-   `Patchwork <https://en.wikipedia.org/wiki/Patchwork_(software)>`__
-   to track the status of patches and also to automatically preview
-   patches.
-
 The following sections provide procedures for submitting a change.
 
 .. _pushing-a-change-upstream:
@@ -10993,6 +10983,19 @@ without using the scripts:
    command, see ``GIT-SEND-EMAIL(1)`` displayed using the
    ``man git-send-email`` command.
 
+The Yocto Project uses a `Patchwork instance <https://patchwork.openembedded.org/>`__
+to track the status of patches submitted to the various mailing lists and to
+support automated patch testing. Each submitted patch is checked for common
+mistakes and deviations from the expected patch format and submitters are
+notified by patchtest if such mistakes are found. This process helps to
+reduce the burden of patch review on maintainers.
+
+.. note::
+
+   This system is imperfect and changes can sometimes get lost in the flow.
+   Asking about the status of a patch or change is reasonable if the change
+   has been idle for a while with no feedback.
+
 Working With Licenses
 =====================
 
-- 
2.20.1

[PATCH 3/8] dev-manual-common-tasks: Tidy up patch submission process

[Paul Barker]

Reduce duplication by pulling out the common steps of committing changes
locally from the steps of submitting those changes via the pull request
scripts or via email.

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

diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
index 2f28cce62..641ca8539 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.rst
+++ b/documentation/dev-manual/dev-manual-common-tasks.rst
@@ -10691,19 +10691,10 @@ layers you are contributing to.
 
 The following sections provide procedures for submitting a change.
 
-.. _pushing-a-change-upstream:
-
-Using Scripts to Push a Change Upstream and Request a Pull
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Follow this procedure to push a change to an upstream "contrib" Git
-repository:
+.. _preparing-changes-for-submissions:
 
-.. note::
-
-   You can find general Git information on how to push a change upstream
-   in the
-   `Git Community Book <https://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows>`__.
+Preparing Changes for Submission
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 1. *Make Your Changes Locally:* Make your changes in your local Git
    repository. You should make small, controlled, isolated changes.
@@ -10785,7 +10776,22 @@ repository:
 
          detailed description of change
 
-4. *Push Your Commits to a "Contrib" Upstream:* If you have arranged for
+.. _pushing-a-change-upstream:
+
+Using Scripts to Push a Change Upstream and Request a Pull
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Follow this procedure to push a change to an upstream "contrib" Git
+repository once the steps in :ref:`preparing-changes-for-submissions` have
+been followed:
+
+.. note::
+
+   You can find general Git information on how to push a change upstream
+   in the
+   `Git Community Book <https://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows>`__.
+
+1. *Push Your Commits to a "Contrib" Upstream:* If you have arranged for
    permissions to push to an upstream contrib repository, push the
    change to that repository:
    ::
@@ -10802,7 +10808,7 @@ repository:
 
       $ git push meta-intel-contrib your_name/README
 
-5. *Determine Who to Notify:* Determine the maintainer or the mailing
+2. *Determine Who to Notify:* Determine the maintainer or the mailing
    list that you need to notify for the change.
 
    Before submitting any change, you need to be sure who the maintainer
@@ -10831,7 +10837,7 @@ repository:
       lists <resources-mailinglist>`" section in
       the Yocto Project Reference Manual.
 
-6. *Make a Pull Request:* Notify the maintainer or the mailing list that
+3. *Make a Pull Request:* Notify the maintainer or the mailing list that
    you have pushed a change by making a pull request.
 
    The Yocto Project provides two scripts that conveniently let you
@@ -10898,29 +10904,10 @@ mailing lists, see the ":ref:`Mailing Lists <resources-mailinglist>`" section in
 Yocto Project Reference Manual.
 
 Here is the general procedure on how to submit a patch through email
-without using the scripts:
-
-1. *Make Your Changes Locally:* Make your changes in your local Git
-   repository. You should make small, controlled, isolated changes.
-   Keeping changes small and isolated aids review, makes
-   merging/rebasing easier and keeps the change history clean should
-   anyone need to refer to it in future.
-
-2. *Stage Your Changes:* Stage your changes by using the ``git add``
-   command on each file you changed.
-
-3. *Commit Your Changes:* Commit the change by using the
-   ``git commit --signoff`` command. Using the ``--signoff`` option
-   identifies you as the person making the change and also satisfies the
-   Developer's Certificate of Origin (DCO) shown earlier.
-
-   When you form a commit, you must follow certain standards established
-   by the Yocto Project development team. See :ref:`Step 3
-   <dev-manual/dev-manual-common-tasks:using scripts to push a change upstream and request a pull>`
-   in the previous section for information on how to provide commit information
-   that meets Yocto Project commit message standards.
+without using the scripts once the steps in
+:ref:`preparing-changes-for-submissions` have been followed:
 
-4. *Format the Commit:* Format the commit into an email message. To
+1. *Format the Commit:* Format the commit into an email message. To
    format commits, use the ``git format-patch`` command. When you
    provide the command, you must include a revision list or a number of
    patches as part of the command. For example, either of these two
@@ -10953,7 +10940,7 @@ without using the scripts:
       or to OpenEmbedded, you might consider requesting a contrib area
       and the necessary associated rights.
 
-5. *Import the Files Into Your Mail Client:* Import the files into your
+2. *Import the Files Into Your Mail Client:* Import the files into your
    mail client by using the ``git send-email`` command.
 
    .. note::
-- 
2.20.1

[PATCH 4/8] dev-manual-common-tasks: Describe git-send-email accurately

[Paul Barker]

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

diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
index 641ca8539..b34602e16 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.rst
+++ b/documentation/dev-manual/dev-manual-common-tasks.rst
@@ -10940,8 +10940,8 @@ without using the scripts once the steps in
       or to OpenEmbedded, you might consider requesting a contrib area
       and the necessary associated rights.
 
-2. *Import the Files Into Your Mail Client:* Import the files into your
-   mail client by using the ``git send-email`` command.
+2. *Send the patches via email:* Send the patches to the recipients and
+   relevant mailing lists by using the ``git send-email`` command.
 
    .. note::
 
-- 
2.20.1

[PATCH 5/8] dev-manual-common-tasks: Describe how to handle patch feedback

[Paul Barker]

The contribution guidelines would benefit from a brief section on how to
address feedback from patch reviewers and how to re-submit amended
patches. The information here is based on my personal experience and on
the existing notes on 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    | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
index b34602e16..0a3ab8241 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.rst
+++ b/documentation/dev-manual/dev-manual-common-tasks.rst
@@ -10983,6 +10983,28 @@ reduce the burden of patch review on maintainers.
    Asking about the status of a patch or change is reasonable if the change
    has been idle for a while with no feedback.
 
+Responding to Patch Review
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You may get feedback on your submitted patches from other community members
+or from the automated patchtest service. If issues are identified in your
+patch then it is usually necessary to address these before the patch will be
+accepted into the project. In this case you should amend the patch according
+to the feedback and submit an updated version to the relevant mailing list,
+copying in the reviewers who provided feedback to the previous version of the
+patch.
+
+The patch should be amended using ``git commit --amend`` or perhaps ``git
+rebase`` for more expert git users. You should also modify the ``[PATCH]``
+tag in the email subject line when sending the revised patch to mark the new
+iteration as ``[PATCH v2]``, ``[PATCH v3]``, etc as appropriate. This can be
+done by passing the ``-v`` argument to ``git format-patch`` with a version
+number.
+
+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.
+
 Working With Licenses
 =====================
 
-- 
2.20.1

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

[Paul Barker]

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>`__.
+
+.. 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
 =====================
 
-- 
2.20.1

[PATCH 7/8] dev-manual-common-tasks: Re-order patch submission instructions

[Paul Barker]

New contributors to the project will usually be following the steps to
submit patches directly via email as they may not have commit access to
a contrib repository. For shorter series of patches this is the more
common workflow which we see anyway.

The documentation here is updated to reflect this, addressing the email
submission process first and then the pull request process. The new
opening paragraph for the section on submitting pull requests is taken
from 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    | 196 +++++++++---------
 1 file changed, 99 insertions(+), 97 deletions(-)

diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
index e923ce834..cde1b80d1 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.rst
+++ b/documentation/dev-manual/dev-manual-common-tasks.rst
@@ -10776,11 +10776,110 @@ Preparing Changes for Submission
 
          detailed description of change
 
+.. _submitting-a-patch:
+
+Using Email to Submit a Patch
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Depending on the components changed, you need to submit the email to a
+specific mailing list. For some guidance on which mailing list to use,
+see the `list <#figuring-out-the-mailing-list-to-use>`__ at the
+beginning of this section. For a description of all the available
+mailing lists, see the ":ref:`Mailing Lists <resources-mailinglist>`" section in the
+Yocto Project Reference Manual.
+
+Here is the general procedure on how to submit a patch through email
+without using the scripts once the steps in
+:ref:`preparing-changes-for-submissions` have been followed:
+
+1. *Format the Commit:* Format the commit into an email message. To
+   format commits, use the ``git format-patch`` command. When you
+   provide the command, you must include a revision list or a number of
+   patches as part of the command. For example, either of these two
+   commands takes your most recent single commit and formats it as an
+   email message in the current directory:
+   ::
+
+      $ git format-patch -1
+
+   or ::
+
+      $ git format-patch HEAD~
+
+   After the command is run, the current directory contains a numbered
+   ``.patch`` file for the commit.
+
+   If you provide several commits as part of the command, the
+   ``git format-patch`` command produces a series of numbered files in
+   the current directory – one for each commit. If you have more than
+   one patch, you should also use the ``--cover`` option with the
+   command, which generates a cover letter as the first "patch" in the
+   series. You can then edit the cover letter to provide a description
+   for the series of patches. For information on the
+   ``git format-patch`` command, see ``GIT_FORMAT_PATCH(1)`` displayed
+   using the ``man git-format-patch`` command.
+
+   .. note::
+
+      If you are or will be a frequent contributor to the Yocto Project
+      or to OpenEmbedded, you might consider requesting a contrib area
+      and the necessary associated rights.
+
+2. *Send the patches via email:* Send the patches to the recipients and
+   relevant mailing lists by using the ``git send-email`` command.
+
+   .. note::
+
+      In order to use ``git send-email``, you must have the proper Git packages
+      installed on your host.
+      For Ubuntu, Debian, and Fedora the package is ``git-email``.
+
+   The ``git send-email`` command sends email by using a local or remote
+   Mail Transport Agent (MTA) such as ``msmtp``, ``sendmail``, or
+   through a direct ``smtp`` configuration in your Git ``~/.gitconfig``
+   file. If you are submitting patches through email only, it is very
+   important that you submit them without any whitespace or HTML
+   formatting that either you or your mailer introduces. The maintainer
+   that receives your patches needs to be able to save and apply them
+   directly from your emails. A good way to verify that what you are
+   sending will be applicable by the maintainer is to do a dry run and
+   send them to yourself and then save and apply them as the maintainer
+   would.
+
+   The ``git send-email`` command is the preferred method for sending
+   your patches using email since there is no risk of compromising
+   whitespace in the body of the message, which can occur when you use
+   your own mail client. The command also has several options that let
+   you specify recipients and perform further editing of the email
+   message. For information on how to use the ``git send-email``
+   command, see ``GIT-SEND-EMAIL(1)`` displayed using the
+   ``man git-send-email`` command.
+
+The Yocto Project uses a `Patchwork instance <https://patchwork.openembedded.org/>`__
+to track the status of patches submitted to the various mailing lists and to
+support automated patch testing. Each submitted patch is checked for common
+mistakes and deviations from the expected patch format and submitters are
+notified by patchtest if such mistakes are found. This process helps to
+reduce the burden of patch review on maintainers.
+
+.. note::
+
+   This system is imperfect and changes can sometimes get lost in the flow.
+   Asking about the status of a patch or change is reasonable if the change
+   has been idle for a while with no feedback.
+
 .. _pushing-a-change-upstream:
 
 Using Scripts to Push a Change Upstream and Request a Pull
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+For larger patch series it is preferable to send a pull request which not
+only includes the patch but also a pointer to a branch that can be pulled
+from. This involves making a local branch for your changes, pushing this
+branch to an accessible repository and then using the ``create-pull-request``
+and ``send-pull-request`` scripts from openembedded-core to create and send a
+patch series with a link to the branch for review.
+
 Follow this procedure to push a change to an upstream "contrib" Git
 repository once the steps in :ref:`preparing-changes-for-submissions` have
 been followed:
@@ -10886,103 +10985,6 @@ been followed:
               $ poky/scripts/create-pull-request -h
               $ poky/scripts/send-pull-request -h
 
-
-.. _submitting-a-patch:
-
-Using Email to Submit a Patch
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can submit patches without using the ``create-pull-request`` and
-``send-pull-request`` scripts described in the previous section.
-However, keep in mind, the preferred method is to use the scripts.
-
-Depending on the components changed, you need to submit the email to a
-specific mailing list. For some guidance on which mailing list to use,
-see the `list <#figuring-out-the-mailing-list-to-use>`__ at the
-beginning of this section. For a description of all the available
-mailing lists, see the ":ref:`Mailing Lists <resources-mailinglist>`" section in the
-Yocto Project Reference Manual.
-
-Here is the general procedure on how to submit a patch through email
-without using the scripts once the steps in
-:ref:`preparing-changes-for-submissions` have been followed:
-
-1. *Format the Commit:* Format the commit into an email message. To
-   format commits, use the ``git format-patch`` command. When you
-   provide the command, you must include a revision list or a number of
-   patches as part of the command. For example, either of these two
-   commands takes your most recent single commit and formats it as an
-   email message in the current directory:
-   ::
-
-      $ git format-patch -1
-
-   or ::
-
-      $ git format-patch HEAD~
-
-   After the command is run, the current directory contains a numbered
-   ``.patch`` file for the commit.
-
-   If you provide several commits as part of the command, the
-   ``git format-patch`` command produces a series of numbered files in
-   the current directory – one for each commit. If you have more than
-   one patch, you should also use the ``--cover`` option with the
-   command, which generates a cover letter as the first "patch" in the
-   series. You can then edit the cover letter to provide a description
-   for the series of patches. For information on the
-   ``git format-patch`` command, see ``GIT_FORMAT_PATCH(1)`` displayed
-   using the ``man git-format-patch`` command.
-
-   .. note::
-
-      If you are or will be a frequent contributor to the Yocto Project
-      or to OpenEmbedded, you might consider requesting a contrib area
-      and the necessary associated rights.
-
-2. *Send the patches via email:* Send the patches to the recipients and
-   relevant mailing lists by using the ``git send-email`` command.
-
-   .. note::
-
-      In order to use ``git send-email``, you must have the proper Git packages
-      installed on your host.
-      For Ubuntu, Debian, and Fedora the package is ``git-email``.
-
-   The ``git send-email`` command sends email by using a local or remote
-   Mail Transport Agent (MTA) such as ``msmtp``, ``sendmail``, or
-   through a direct ``smtp`` configuration in your Git ``~/.gitconfig``
-   file. If you are submitting patches through email only, it is very
-   important that you submit them without any whitespace or HTML
-   formatting that either you or your mailer introduces. The maintainer
-   that receives your patches needs to be able to save and apply them
-   directly from your emails. A good way to verify that what you are
-   sending will be applicable by the maintainer is to do a dry run and
-   send them to yourself and then save and apply them as the maintainer
-   would.
-
-   The ``git send-email`` command is the preferred method for sending
-   your patches using email since there is no risk of compromising
-   whitespace in the body of the message, which can occur when you use
-   your own mail client. The command also has several options that let
-   you specify recipients and perform further editing of the email
-   message. For information on how to use the ``git send-email``
-   command, see ``GIT-SEND-EMAIL(1)`` displayed using the
-   ``man git-send-email`` command.
-
-The Yocto Project uses a `Patchwork instance <https://patchwork.openembedded.org/>`__
-to track the status of patches submitted to the various mailing lists and to
-support automated patch testing. Each submitted patch is checked for common
-mistakes and deviations from the expected patch format and submitters are
-notified by patchtest if such mistakes are found. This process helps to
-reduce the burden of patch review on maintainers.
-
-.. note::
-
-   This system is imperfect and changes can sometimes get lost in the flow.
-   Asking about the status of a patch or change is reasonable if the change
-   has been idle for a while with no feedback.
-
 Responding to Patch Review
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
2.20.1

[PATCH 8/8] documentation/README: Refer to top-level README for contributions

[Paul Barker]

This may help anyone looking for patch contribution guidelines in the
documentation directory itself.

Signed-off-by: Paul Barker <pbarker@konsulko.com>
---
 documentation/README | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/documentation/README b/documentation/README
index 534ae66f8..5beed2517 100644
--- a/documentation/README
+++ b/documentation/README
@@ -318,3 +318,9 @@ References to the bitbake manual can be done like this:
   See the ":ref:`-D <bitbake:bitbake-user-manual/bitbake-user-manual-intro:usage and syntax>`" option
 or
   :term:`bitbake:BB_NUMBER_PARSE_THREADS`
+
+Submitting documentation changes
+================================
+
+Please see the top level README file in this repository for details of where
+to send patches.
-- 
2.20.1

Re: [PATCH 1/8] dev-manual-common-tasks: Fix refs to testing branches

[Paul Barker]

On Wed, 11 Nov 2020 at 16:08, Paul Barker <pbarker@konsulko.com> wrote:
>
> After discussions on IRC with Ross we concluded that the `ross/mut`
> branch shouldn't really be listed in the docs as it's more of a personal
> test branch. Instead we should list the -next branches for
> openembedded-core and poky.
>
> Signed-off-by: Paul Barker <pbarker@konsulko.com>

Cc: Ross.

> ---
>  .../dev-manual/dev-manual-common-tasks.rst    | 35 ++++++++++++-------
>  1 file changed, 23 insertions(+), 12 deletions(-)
>
> diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
> index 27aacde60..698b27377 100644
> --- a/documentation/dev-manual/dev-manual-common-tasks.rst
> +++ b/documentation/dev-manual/dev-manual-common-tasks.rst
> @@ -10665,18 +10665,29 @@ to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a
>  section in the Yocto Project Overview and Concepts Manual for additional
>  concepts on working in the Yocto Project development environment.
>
> -Two commonly used testing repositories exist for OpenEmbedded-Core:
> -
> --  *"ross/mut" branch:* The "mut" (master-under-test) tree exists in the
> -   ``poky-contrib`` repository in the
> -   :yocto_git:`Yocto Project source repositories <>`.
> -
> --  *"master-next" branch:* This branch is part of the main "poky"
> -   repository in the Yocto Project source repositories.
> -
> -Maintainers use these branches to test submissions prior to merging
> -patches. Thus, you can get an idea of the status of a patch based on
> -whether the patch has been merged into one of these branches.
> +Maintainers commonly use ``-next`` branches to test submissions prior to
> +merging patches. Thus, you can get an idea of the status of a patch based on
> +whether the patch has been merged into one of these branches. The commonly
> +used testing branches for OpenEmbedded-Core are as follows:
> +
> +-  *openembedded-core "master-next" branch:* This branch is part of the
> +   `openembedded-core <https://git.openembedded.org/openembedded-core/>`__
> +   repository on git.openembedded.org and contains proposed changes to the
> +   core metadata.
> +
> +-  *poky "master-next" branch:* This branch is part of the
> +   `poky <https://git.yoctoproject.org/cgit/cgit.cgi/poky/>`__
> +   repository on git.yoctoproject.org and combines proposed changes to
> +   bitbake, the core metadata and the poky distro.
> +
> +Similarly, stable branches maintained by the project may have corresponding
> +``-next`` branches which collect proposed changes. For example,
> +``dunfell-next`` and ``gatesgarth-next`` branches in both the
> +"openembdedded-core" and "poky" repositories.
> +
> +Other layers may have similar testing branches but there is no formal
> +requirement or standard for these so please check the documentation for the
> +layers you are contributing to.
>
>  .. note::
>
> --
> 2.20.1
>


-- 
Paul Barker
Konsulko Group

Re: [docs] [PATCH 1/8] dev-manual-common-tasks: Fix refs to testing branches

[Quentin Schulz]

Hi Paul,

On Wed, Nov 11, 2020 at 04:07:53PM +0000, Paul Barker wrote:
> After discussions on IRC with Ross we concluded that the `ross/mut`
> branch shouldn't really be listed in the docs as it's more of a personal
> test branch. Instead we should list the -next branches for
> openembedded-core and poky.
> 
> Signed-off-by: Paul Barker <pbarker@konsulko.com>
> ---
>  .../dev-manual/dev-manual-common-tasks.rst    | 35 ++++++++++++-------
>  1 file changed, 23 insertions(+), 12 deletions(-)
> 
> diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
> index 27aacde60..698b27377 100644
> --- a/documentation/dev-manual/dev-manual-common-tasks.rst
> +++ b/documentation/dev-manual/dev-manual-common-tasks.rst
> @@ -10665,18 +10665,29 @@ to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a
>  section in the Yocto Project Overview and Concepts Manual for additional
>  concepts on working in the Yocto Project development environment.
>  
> -Two commonly used testing repositories exist for OpenEmbedded-Core:
> -
> --  *"ross/mut" branch:* The "mut" (master-under-test) tree exists in the
> -   ``poky-contrib`` repository in the
> -   :yocto_git:`Yocto Project source repositories <>`.
> -
> --  *"master-next" branch:* This branch is part of the main "poky"
> -   repository in the Yocto Project source repositories.
> -
> -Maintainers use these branches to test submissions prior to merging
> -patches. Thus, you can get an idea of the status of a patch based on
> -whether the patch has been merged into one of these branches.
> +Maintainers commonly use ``-next`` branches to test submissions prior to
> +merging patches. Thus, you can get an idea of the status of a patch based on
> +whether the patch has been merged into one of these branches. The commonly
> +used testing branches for OpenEmbedded-Core are as follows:
> +
> +-  *openembedded-core "master-next" branch:* This branch is part of the
> +   `openembedded-core <https://git.openembedded.org/openembedded-core/>`__

Side note: should we add a :oe_git: directive as we already have :yocto_git:?

> +   repository on git.openembedded.org and contains proposed changes to the
> +   core metadata.
> +
> +-  *poky "master-next" branch:* This branch is part of the
> +   `poky <https://git.yoctoproject.org/cgit/cgit.cgi/poky/>`__

:yocto_git:`poky </cgit/cgit.cgi/poky/>`

> +   repository on git.yoctoproject.org and combines proposed changes to

Maybe s/git.yoctoproject.org/&YOCTO_GIT_URL;/ ? Not convinced though, no
hard feeling if this is not taken into account.

Thanks,
Quentin

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

[Quentin Schulz]

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

Re: [docs] [PATCH 7/8] dev-manual-common-tasks: Re-order patch submission instructions

[Quentin Schulz]

Hi Paul,

On Wed, Nov 11, 2020 at 04:07:59PM +0000, Paul Barker wrote:
> New contributors to the project will usually be following the steps to
> submit patches directly via email as they may not have commit access to
> a contrib repository. For shorter series of patches this is the more
> common workflow which we see anyway.
> 
> The documentation here is updated to reflect this, addressing the email
> submission process first and then the pull request process. The new
> opening paragraph for the section on submitting pull requests is taken
> from 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    | 196 +++++++++---------
>  1 file changed, 99 insertions(+), 97 deletions(-)
> 
> diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
> index e923ce834..cde1b80d1 100644
> --- a/documentation/dev-manual/dev-manual-common-tasks.rst
> +++ b/documentation/dev-manual/dev-manual-common-tasks.rst
> @@ -10776,11 +10776,110 @@ Preparing Changes for Submission
>  
>           detailed description of change
>  
> +.. _submitting-a-patch:
> +
> +Using Email to Submit a Patch
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Depending on the components changed, you need to submit the email to a
> +specific mailing list. For some guidance on which mailing list to use,
> +see the `list <#figuring-out-the-mailing-list-to-use>`__ at the

#figuring-out-the-mailing-list-to-use does not actually exist.

Maybe adding:
.. _figuring-out-the-mailing-list-to-use:
right before "The "poky" repository, which is the Yocto Project's
reference build environment" would work but not guaranteed, in any case
you would need to use :ref:`list <some-ref>` instead as failing to find
the link will fail the sphinx build instead of silently ignoring it.

Otherwise, please link to :ref:`list <how-to-submit-a-change>`.

> +beginning of this section. For a description of all the available
> +mailing lists, see the ":ref:`Mailing Lists <resources-mailinglist>`" section in the
> +Yocto Project Reference Manual.
> +
> +Here is the general procedure on how to submit a patch through email
> +without using the scripts once the steps in
> +:ref:`preparing-changes-for-submissions` have been followed:
> +
> +1. *Format the Commit:* Format the commit into an email message. To
> +   format commits, use the ``git format-patch`` command. When you
> +   provide the command, you must include a revision list or a number of
> +   patches as part of the command. For example, either of these two
> +   commands takes your most recent single commit and formats it as an
> +   email message in the current directory:
> +   ::

email message in the current directory::

This is the same as above and we're striving for consistency.

> +
> +      $ git format-patch -1
> +
> +   or ::

If you don't want a colon, great, otherwise remove the leading space
before the two colons.

> +
> +      $ git format-patch HEAD~
> +
> +   After the command is run, the current directory contains a numbered
> +   ``.patch`` file for the commit.
> +
> +   If you provide several commits as part of the command, the
> +   ``git format-patch`` command produces a series of numbered files in
> +   the current directory – one for each commit. If you have more than

I don't know if we want to keep this – instead of a "normal" dash (-)?
Makes it harder to grep in the sources.

> +   one patch, you should also use the ``--cover`` option with the
> +   command, which generates a cover letter as the first "patch" in the
> +   series. You can then edit the cover letter to provide a description
> +   for the series of patches. For information on the
> +   ``git format-patch`` command, see ``GIT_FORMAT_PATCH(1)`` displayed
> +   using the ``man git-format-patch`` command.
> +
> +   .. note::
> +
> +      If you are or will be a frequent contributor to the Yocto Project
> +      or to OpenEmbedded, you might consider requesting a contrib area
> +      and the necessary associated rights.
> +
> +2. *Send the patches via email:* Send the patches to the recipients and
> +   relevant mailing lists by using the ``git send-email`` command.
> +
> +   .. note::
> +
> +      In order to use ``git send-email``, you must have the proper Git packages
> +      installed on your host.
> +      For Ubuntu, Debian, and Fedora the package is ``git-email``.
> +
> +   The ``git send-email`` command sends email by using a local or remote
> +   Mail Transport Agent (MTA) such as ``msmtp``, ``sendmail``, or
> +   through a direct ``smtp`` configuration in your Git ``~/.gitconfig``
> +   file. If you are submitting patches through email only, it is very
> +   important that you submit them without any whitespace or HTML
> +   formatting that either you or your mailer introduces. The maintainer
> +   that receives your patches needs to be able to save and apply them
> +   directly from your emails. A good way to verify that what you are
> +   sending will be applicable by the maintainer is to do a dry run and
> +   send them to yourself and then save and apply them as the maintainer
> +   would.
> +

Would benefit to explain "as the maintainer would". I guess we're
talking about `git am`?

> +   The ``git send-email`` command is the preferred method for sending
> +   your patches using email since there is no risk of compromising
> +   whitespace in the body of the message, which can occur when you use
> +   your own mail client. The command also has several options that let
> +   you specify recipients and perform further editing of the email
> +   message. For information on how to use the ``git send-email``
> +   command, see ``GIT-SEND-EMAIL(1)`` displayed using the
> +   ``man git-send-email`` command.
> +
> +The Yocto Project uses a `Patchwork instance <https://patchwork.openembedded.org/>`__
> +to track the status of patches submitted to the various mailing lists and to
> +support automated patch testing. Each submitted patch is checked for common
> +mistakes and deviations from the expected patch format and submitters are
> +notified by patchtest if such mistakes are found. This process helps to
> +reduce the burden of patch review on maintainers.
> +
> +.. note::
> +
> +   This system is imperfect and changes can sometimes get lost in the flow.
> +   Asking about the status of a patch or change is reasonable if the change
> +   has been idle for a while with no feedback.
> +
>  .. _pushing-a-change-upstream:
>  
>  Using Scripts to Push a Change Upstream and Request a Pull
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  
> +For larger patch series it is preferable to send a pull request which not

Do we want to define what we mean by "larger"? (e.g. 10+?)

> +only includes the patch but also a pointer to a branch that can be pulled
> +from. This involves making a local branch for your changes, pushing this
> +branch to an accessible repository and then using the ``create-pull-request``
> +and ``send-pull-request`` scripts from openembedded-core to create and send a
> +patch series with a link to the branch for review.
> +
>  Follow this procedure to push a change to an upstream "contrib" Git
>  repository once the steps in :ref:`preparing-changes-for-submissions` have
>  been followed:
> @@ -10886,103 +10985,6 @@ been followed:
>                $ poky/scripts/create-pull-request -h
>                $ poky/scripts/send-pull-request -h
>  
> -
> -.. _submitting-a-patch:
> -
> -Using Email to Submit a Patch
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> -
> -You can submit patches without using the ``create-pull-request`` and
> -``send-pull-request`` scripts described in the previous section.
> -However, keep in mind, the preferred method is to use the scripts.
> -
> -Depending on the components changed, you need to submit the email to a
> -specific mailing list. For some guidance on which mailing list to use,
> -see the `list <#figuring-out-the-mailing-list-to-use>`__ at the
> -beginning of this section. For a description of all the available
> -mailing lists, see the ":ref:`Mailing Lists <resources-mailinglist>`" section in the
> -Yocto Project Reference Manual.
> -
> -Here is the general procedure on how to submit a patch through email
> -without using the scripts once the steps in
> -:ref:`preparing-changes-for-submissions` have been followed:
> -
> -1. *Format the Commit:* Format the commit into an email message. To
> -   format commits, use the ``git format-patch`` command. When you
> -   provide the command, you must include a revision list or a number of
> -   patches as part of the command. For example, either of these two
> -   commands takes your most recent single commit and formats it as an
> -   email message in the current directory:
> -   ::
> -
> -      $ git format-patch -1
> -
> -   or ::
> -
> -      $ git format-patch HEAD~
> -
> -   After the command is run, the current directory contains a numbered
> -   ``.patch`` file for the commit.
> -
> -   If you provide several commits as part of the command, the
> -   ``git format-patch`` command produces a series of numbered files in
> -   the current directory – one for each commit. If you have more than
> -   one patch, you should also use the ``--cover`` option with the
> -   command, which generates a cover letter as the first "patch" in the
> -   series. You can then edit the cover letter to provide a description
> -   for the series of patches. For information on the
> -   ``git format-patch`` command, see ``GIT_FORMAT_PATCH(1)`` displayed
> -   using the ``man git-format-patch`` command.
> -
> -   .. note::
> -
> -      If you are or will be a frequent contributor to the Yocto Project
> -      or to OpenEmbedded, you might consider requesting a contrib area
> -      and the necessary associated rights.
> -
> -2. *Send the patches via email:* Send the patches to the recipients and
> -   relevant mailing lists by using the ``git send-email`` command.
> -
> -   .. note::
> -
> -      In order to use ``git send-email``, you must have the proper Git packages
> -      installed on your host.
> -      For Ubuntu, Debian, and Fedora the package is ``git-email``.
> -
> -   The ``git send-email`` command sends email by using a local or remote
> -   Mail Transport Agent (MTA) such as ``msmtp``, ``sendmail``, or
> -   through a direct ``smtp`` configuration in your Git ``~/.gitconfig``
> -   file. If you are submitting patches through email only, it is very
> -   important that you submit them without any whitespace or HTML
> -   formatting that either you or your mailer introduces. The maintainer
> -   that receives your patches needs to be able to save and apply them
> -   directly from your emails. A good way to verify that what you are
> -   sending will be applicable by the maintainer is to do a dry run and
> -   send them to yourself and then save and apply them as the maintainer
> -   would.
> -
> -   The ``git send-email`` command is the preferred method for sending
> -   your patches using email since there is no risk of compromising
> -   whitespace in the body of the message, which can occur when you use
> -   your own mail client. The command also has several options that let
> -   you specify recipients and perform further editing of the email
> -   message. For information on how to use the ``git send-email``
> -   command, see ``GIT-SEND-EMAIL(1)`` displayed using the
> -   ``man git-send-email`` command.
> -
> -The Yocto Project uses a `Patchwork instance <https://patchwork.openembedded.org/>`__
> -to track the status of patches submitted to the various mailing lists and to
> -support automated patch testing. Each submitted patch is checked for common
> -mistakes and deviations from the expected patch format and submitters are
> -notified by patchtest if such mistakes are found. This process helps to
> -reduce the burden of patch review on maintainers.
> -
> -.. note::
> -
> -   This system is imperfect and changes can sometimes get lost in the flow.
> -   Asking about the status of a patch or change is reasonable if the change
> -   has been idle for a while with no feedback.
> -
>  Responding to Patch Review
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~
>  

Ah. It's just re-ordering text... Well... forget about it then :)

Free patches for anyone willing to send them :)

Quentin

Re: [docs] [PATCH 1/8] dev-manual-common-tasks: Fix refs to testing branches

[Richard Purdie]

On Wed, 2020-11-11 at 16:27 +0000, Paul Barker wrote:
> On Wed, 11 Nov 2020 at 16:08, Paul Barker <pbarker@konsulko.com>
> wrote:
> > After discussions on IRC with Ross we concluded that the `ross/mut`
> > branch shouldn't really be listed in the docs as it's more of a
> > personal
> > test branch. Instead we should list the -next branches for
> > openembedded-core and poky.
> > 
> > Signed-off-by: Paul Barker <pbarker@konsulko.com>
> 
> Cc: Ross.

Just for reference the testing manual was written around 12-18 months
ago and reflected the status quo at that time. The world has changed a
bit.

Cheers,

Richard

Re: [docs] [PATCH 1/8] dev-manual-common-tasks: Fix refs to testing branches

[Nicolas Dechesne]

On Wed, Nov 11, 2020 at 5:28 PM Quentin Schulz
<quentin.schulz@streamunlimited.com> wrote:
>
> Hi Paul,
>
> On Wed, Nov 11, 2020 at 04:07:53PM +0000, Paul Barker wrote:
> > After discussions on IRC with Ross we concluded that the `ross/mut`
> > branch shouldn't really be listed in the docs as it's more of a personal
> > test branch. Instead we should list the -next branches for
> > openembedded-core and poky.
> >
> > Signed-off-by: Paul Barker <pbarker@konsulko.com>
> > ---
> >  .../dev-manual/dev-manual-common-tasks.rst    | 35 ++++++++++++-------
> >  1 file changed, 23 insertions(+), 12 deletions(-)
> >
> > diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
> > index 27aacde60..698b27377 100644
> > --- a/documentation/dev-manual/dev-manual-common-tasks.rst
> > +++ b/documentation/dev-manual/dev-manual-common-tasks.rst
> > @@ -10665,18 +10665,29 @@ to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a
> >  section in the Yocto Project Overview and Concepts Manual for additional
> >  concepts on working in the Yocto Project development environment.
> >
> > -Two commonly used testing repositories exist for OpenEmbedded-Core:
> > -
> > --  *"ross/mut" branch:* The "mut" (master-under-test) tree exists in the
> > -   ``poky-contrib`` repository in the
> > -   :yocto_git:`Yocto Project source repositories <>`.
> > -
> > --  *"master-next" branch:* This branch is part of the main "poky"
> > -   repository in the Yocto Project source repositories.
> > -
> > -Maintainers use these branches to test submissions prior to merging
> > -patches. Thus, you can get an idea of the status of a patch based on
> > -whether the patch has been merged into one of these branches.
> > +Maintainers commonly use ``-next`` branches to test submissions prior to
> > +merging patches. Thus, you can get an idea of the status of a patch based on
> > +whether the patch has been merged into one of these branches. The commonly
> > +used testing branches for OpenEmbedded-Core are as follows:
> > +
> > +-  *openembedded-core "master-next" branch:* This branch is part of the
> > +   `openembedded-core <https://git.openembedded.org/openembedded-core/>`__
>
> Side note: should we add a :oe_git: directive as we already have :yocto_git:?
>
> > +   repository on git.openembedded.org and contains proposed changes to the
> > +   core metadata.
> > +
> > +-  *poky "master-next" branch:* This branch is part of the
> > +   `poky <https://git.yoctoproject.org/cgit/cgit.cgi/poky/>`__
>
> :yocto_git:`poky </cgit/cgit.cgi/poky/>`
>
> > +   repository on git.yoctoproject.org and combines proposed changes to
>
> Maybe s/git.yoctoproject.org/&YOCTO_GIT_URL;/ ? Not convinced though, no
> hard feeling if this is not taken into account.

or :yocto_git:`/` like we do in other places? It would render as
https://git.yoctoproject.org/ , not git.yoctoproject.org, but I think
it's better, no?

>
> Thanks,
> Quentin
>
> 
>

Re: [docs] [PATCH 1/8] dev-manual-common-tasks: Fix refs to testing branches

[Quentin Schulz]

On Wed, Nov 11, 2020 at 06:25:45PM +0100, Nicolas Dechesne wrote:
> On Wed, Nov 11, 2020 at 5:28 PM Quentin Schulz
> <quentin.schulz@streamunlimited.com> wrote:
> >
> > Hi Paul,
> >
> > On Wed, Nov 11, 2020 at 04:07:53PM +0000, Paul Barker wrote:
> > > After discussions on IRC with Ross we concluded that the `ross/mut`
> > > branch shouldn't really be listed in the docs as it's more of a personal
> > > test branch. Instead we should list the -next branches for
> > > openembedded-core and poky.
> > >
> > > Signed-off-by: Paul Barker <pbarker@konsulko.com>
> > > ---
> > >  .../dev-manual/dev-manual-common-tasks.rst    | 35 ++++++++++++-------
> > >  1 file changed, 23 insertions(+), 12 deletions(-)
> > >
> > > diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
> > > index 27aacde60..698b27377 100644
> > > --- a/documentation/dev-manual/dev-manual-common-tasks.rst
> > > +++ b/documentation/dev-manual/dev-manual-common-tasks.rst
> > > @@ -10665,18 +10665,29 @@ to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a
> > >  section in the Yocto Project Overview and Concepts Manual for additional
> > >  concepts on working in the Yocto Project development environment.
> > >
> > > -Two commonly used testing repositories exist for OpenEmbedded-Core:
> > > -
> > > --  *"ross/mut" branch:* The "mut" (master-under-test) tree exists in the
> > > -   ``poky-contrib`` repository in the
> > > -   :yocto_git:`Yocto Project source repositories <>`.
> > > -
> > > --  *"master-next" branch:* This branch is part of the main "poky"
> > > -   repository in the Yocto Project source repositories.
> > > -
> > > -Maintainers use these branches to test submissions prior to merging
> > > -patches. Thus, you can get an idea of the status of a patch based on
> > > -whether the patch has been merged into one of these branches.
> > > +Maintainers commonly use ``-next`` branches to test submissions prior to
> > > +merging patches. Thus, you can get an idea of the status of a patch based on
> > > +whether the patch has been merged into one of these branches. The commonly
> > > +used testing branches for OpenEmbedded-Core are as follows:
> > > +
> > > +-  *openembedded-core "master-next" branch:* This branch is part of the
> > > +   `openembedded-core <https://git.openembedded.org/openembedded-core/>`__
> >
> > Side note: should we add a :oe_git: directive as we already have :yocto_git:?
> >
> > > +   repository on git.openembedded.org and contains proposed changes to the
> > > +   core metadata.
> > > +
> > > +-  *poky "master-next" branch:* This branch is part of the
> > > +   `poky <https://git.yoctoproject.org/cgit/cgit.cgi/poky/>`__
> >
> > :yocto_git:`poky </cgit/cgit.cgi/poky/>`
> >
> > > +   repository on git.yoctoproject.org and combines proposed changes to
> >
> > Maybe s/git.yoctoproject.org/&YOCTO_GIT_URL;/ ? Not convinced though, no
> > hard feeling if this is not taken into account.
> 
> or :yocto_git:`/` like we do in other places? It would render as
> https://git.yoctoproject.org/ , not git.yoctoproject.org, but I think
> it's better, no?
> 

+1 for the obvious, completely missed it.

Though, now, not sure we need to state that it's from
git.yoctoproject.org while actually giving a direct link to the poky
repo a few words before?

Quentin

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

[Nicolas Dechesne]

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
>
> 
>

Re: [docs] [PATCH 7/8] dev-manual-common-tasks: Re-order patch submission instructions

[Paul Barker]

On Wed, 11 Nov 2020 at 16:57, Quentin Schulz
<quentin.schulz@streamunlimited.com> wrote:
>
> Hi Paul,
>
> On Wed, Nov 11, 2020 at 04:07:59PM +0000, Paul Barker wrote:
> > New contributors to the project will usually be following the steps to
> > submit patches directly via email as they may not have commit access to
> > a contrib repository. For shorter series of patches this is the more
> > common workflow which we see anyway.
> >
> > The documentation here is updated to reflect this, addressing the email
> > submission process first and then the pull request process. The new
> > opening paragraph for the section on submitting pull requests is taken
> > from 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    | 196 +++++++++---------
> >  1 file changed, 99 insertions(+), 97 deletions(-)
> >
> > diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
> > index e923ce834..cde1b80d1 100644
> > --- a/documentation/dev-manual/dev-manual-common-tasks.rst
> > +++ b/documentation/dev-manual/dev-manual-common-tasks.rst
> > @@ -10776,11 +10776,110 @@ Preparing Changes for Submission
> >
> >           detailed description of change
> >
> > +.. _submitting-a-patch:
> > +
> > +Using Email to Submit a Patch
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +Depending on the components changed, you need to submit the email to a
> > +specific mailing list. For some guidance on which mailing list to use,
> > +see the `list <#figuring-out-the-mailing-list-to-use>`__ at the
>
> #figuring-out-the-mailing-list-to-use does not actually exist.
>
> Maybe adding:
> .. _figuring-out-the-mailing-list-to-use:
> right before "The "poky" repository, which is the Yocto Project's
> reference build environment" would work but not guaranteed, in any case
> you would need to use :ref:`list <some-ref>` instead as failing to find
> the link will fail the sphinx build instead of silently ignoring it.
>
> Otherwise, please link to :ref:`list <how-to-submit-a-change>`.
>
> > +beginning of this section. For a description of all the available
> > +mailing lists, see the ":ref:`Mailing Lists <resources-mailinglist>`" section in the
> > +Yocto Project Reference Manual.
> > +
> > +Here is the general procedure on how to submit a patch through email
> > +without using the scripts once the steps in
> > +:ref:`preparing-changes-for-submissions` have been followed:
> > +
> > +1. *Format the Commit:* Format the commit into an email message. To
> > +   format commits, use the ``git format-patch`` command. When you
> > +   provide the command, you must include a revision list or a number of
> > +   patches as part of the command. For example, either of these two
> > +   commands takes your most recent single commit and formats it as an
> > +   email message in the current directory:
> > +   ::
>
> email message in the current directory::
>
> This is the same as above and we're striving for consistency.
>
> > +
> > +      $ git format-patch -1
> > +
> > +   or ::
>
> If you don't want a colon, great, otherwise remove the leading space
> before the two colons.
>
> > +
> > +      $ git format-patch HEAD~
> > +
> > +   After the command is run, the current directory contains a numbered
> > +   ``.patch`` file for the commit.
> > +
> > +   If you provide several commits as part of the command, the
> > +   ``git format-patch`` command produces a series of numbered files in
> > +   the current directory – one for each commit. If you have more than
>
> I don't know if we want to keep this – instead of a "normal" dash (-)?
> Makes it harder to grep in the sources.
>
> > +   one patch, you should also use the ``--cover`` option with the
> > +   command, which generates a cover letter as the first "patch" in the
> > +   series. You can then edit the cover letter to provide a description
> > +   for the series of patches. For information on the
> > +   ``git format-patch`` command, see ``GIT_FORMAT_PATCH(1)`` displayed
> > +   using the ``man git-format-patch`` command.
> > +
> > +   .. note::
> > +
> > +      If you are or will be a frequent contributor to the Yocto Project
> > +      or to OpenEmbedded, you might consider requesting a contrib area
> > +      and the necessary associated rights.
> > +
> > +2. *Send the patches via email:* Send the patches to the recipients and
> > +   relevant mailing lists by using the ``git send-email`` command.
> > +
> > +   .. note::
> > +
> > +      In order to use ``git send-email``, you must have the proper Git packages
> > +      installed on your host.
> > +      For Ubuntu, Debian, and Fedora the package is ``git-email``.
> > +
> > +   The ``git send-email`` command sends email by using a local or remote
> > +   Mail Transport Agent (MTA) such as ``msmtp``, ``sendmail``, or
> > +   through a direct ``smtp`` configuration in your Git ``~/.gitconfig``
> > +   file. If you are submitting patches through email only, it is very
> > +   important that you submit them without any whitespace or HTML
> > +   formatting that either you or your mailer introduces. The maintainer
> > +   that receives your patches needs to be able to save and apply them
> > +   directly from your emails. A good way to verify that what you are
> > +   sending will be applicable by the maintainer is to do a dry run and
> > +   send them to yourself and then save and apply them as the maintainer
> > +   would.
> > +
>
> Would benefit to explain "as the maintainer would". I guess we're
> talking about `git am`?
>
> > +   The ``git send-email`` command is the preferred method for sending
> > +   your patches using email since there is no risk of compromising
> > +   whitespace in the body of the message, which can occur when you use
> > +   your own mail client. The command also has several options that let
> > +   you specify recipients and perform further editing of the email
> > +   message. For information on how to use the ``git send-email``
> > +   command, see ``GIT-SEND-EMAIL(1)`` displayed using the
> > +   ``man git-send-email`` command.
> > +
> > +The Yocto Project uses a `Patchwork instance <https://patchwork.openembedded.org/>`__
> > +to track the status of patches submitted to the various mailing lists and to
> > +support automated patch testing. Each submitted patch is checked for common
> > +mistakes and deviations from the expected patch format and submitters are
> > +notified by patchtest if such mistakes are found. This process helps to
> > +reduce the burden of patch review on maintainers.
> > +
> > +.. note::
> > +
> > +   This system is imperfect and changes can sometimes get lost in the flow.
> > +   Asking about the status of a patch or change is reasonable if the change
> > +   has been idle for a while with no feedback.
> > +
> >  .. _pushing-a-change-upstream:
> >
> >  Using Scripts to Push a Change Upstream and Request a Pull
> >  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> >
> > +For larger patch series it is preferable to send a pull request which not
>
> Do we want to define what we mean by "larger"? (e.g. 10+?)
>
> > +only includes the patch but also a pointer to a branch that can be pulled
> > +from. This involves making a local branch for your changes, pushing this
> > +branch to an accessible repository and then using the ``create-pull-request``
> > +and ``send-pull-request`` scripts from openembedded-core to create and send a
> > +patch series with a link to the branch for review.
> > +
> >  Follow this procedure to push a change to an upstream "contrib" Git
> >  repository once the steps in :ref:`preparing-changes-for-submissions` have
> >  been followed:
> > @@ -10886,103 +10985,6 @@ been followed:
> >                $ poky/scripts/create-pull-request -h
> >                $ poky/scripts/send-pull-request -h
> >
> > -
> > -.. _submitting-a-patch:
> > -
> > -Using Email to Submit a Patch
> > -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > -
> > -You can submit patches without using the ``create-pull-request`` and
> > -``send-pull-request`` scripts described in the previous section.
> > -However, keep in mind, the preferred method is to use the scripts.
> > -
> > -Depending on the components changed, you need to submit the email to a
> > -specific mailing list. For some guidance on which mailing list to use,
> > -see the `list <#figuring-out-the-mailing-list-to-use>`__ at the
> > -beginning of this section. For a description of all the available
> > -mailing lists, see the ":ref:`Mailing Lists <resources-mailinglist>`" section in the
> > -Yocto Project Reference Manual.
> > -
> > -Here is the general procedure on how to submit a patch through email
> > -without using the scripts once the steps in
> > -:ref:`preparing-changes-for-submissions` have been followed:
> > -
> > -1. *Format the Commit:* Format the commit into an email message. To
> > -   format commits, use the ``git format-patch`` command. When you
> > -   provide the command, you must include a revision list or a number of
> > -   patches as part of the command. For example, either of these two
> > -   commands takes your most recent single commit and formats it as an
> > -   email message in the current directory:
> > -   ::
> > -
> > -      $ git format-patch -1
> > -
> > -   or ::
> > -
> > -      $ git format-patch HEAD~
> > -
> > -   After the command is run, the current directory contains a numbered
> > -   ``.patch`` file for the commit.
> > -
> > -   If you provide several commits as part of the command, the
> > -   ``git format-patch`` command produces a series of numbered files in
> > -   the current directory – one for each commit. If you have more than
> > -   one patch, you should also use the ``--cover`` option with the
> > -   command, which generates a cover letter as the first "patch" in the
> > -   series. You can then edit the cover letter to provide a description
> > -   for the series of patches. For information on the
> > -   ``git format-patch`` command, see ``GIT_FORMAT_PATCH(1)`` displayed
> > -   using the ``man git-format-patch`` command.
> > -
> > -   .. note::
> > -
> > -      If you are or will be a frequent contributor to the Yocto Project
> > -      or to OpenEmbedded, you might consider requesting a contrib area
> > -      and the necessary associated rights.
> > -
> > -2. *Send the patches via email:* Send the patches to the recipients and
> > -   relevant mailing lists by using the ``git send-email`` command.
> > -
> > -   .. note::
> > -
> > -      In order to use ``git send-email``, you must have the proper Git packages
> > -      installed on your host.
> > -      For Ubuntu, Debian, and Fedora the package is ``git-email``.
> > -
> > -   The ``git send-email`` command sends email by using a local or remote
> > -   Mail Transport Agent (MTA) such as ``msmtp``, ``sendmail``, or
> > -   through a direct ``smtp`` configuration in your Git ``~/.gitconfig``
> > -   file. If you are submitting patches through email only, it is very
> > -   important that you submit them without any whitespace or HTML
> > -   formatting that either you or your mailer introduces. The maintainer
> > -   that receives your patches needs to be able to save and apply them
> > -   directly from your emails. A good way to verify that what you are
> > -   sending will be applicable by the maintainer is to do a dry run and
> > -   send them to yourself and then save and apply them as the maintainer
> > -   would.
> > -
> > -   The ``git send-email`` command is the preferred method for sending
> > -   your patches using email since there is no risk of compromising
> > -   whitespace in the body of the message, which can occur when you use
> > -   your own mail client. The command also has several options that let
> > -   you specify recipients and perform further editing of the email
> > -   message. For information on how to use the ``git send-email``
> > -   command, see ``GIT-SEND-EMAIL(1)`` displayed using the
> > -   ``man git-send-email`` command.
> > -
> > -The Yocto Project uses a `Patchwork instance <https://patchwork.openembedded.org/>`__
> > -to track the status of patches submitted to the various mailing lists and to
> > -support automated patch testing. Each submitted patch is checked for common
> > -mistakes and deviations from the expected patch format and submitters are
> > -notified by patchtest if such mistakes are found. This process helps to
> > -reduce the burden of patch review on maintainers.
> > -
> > -.. note::
> > -
> > -   This system is imperfect and changes can sometimes get lost in the flow.
> > -   Asking about the status of a patch or change is reasonable if the change
> > -   has been idle for a while with no feedback.
> > -
> >  Responding to Patch Review
> >  ~~~~~~~~~~~~~~~~~~~~~~~~~~
> >
>
> Ah. It's just re-ordering text... Well... forget about it then :)
>
> Free patches for anyone willing to send them :)

This is all good feedback and I'll definitely keep a pin in it for
looking at later. For now I just want to re-order what we already
have.

Thanks,

-- 
Paul Barker
Konsulko Group

Re: [docs] [PATCH 1/8] dev-manual-common-tasks: Fix refs to testing branches

[Paul Barker]

On Wed, 11 Nov 2020 at 17:29, Quentin Schulz
<quentin.schulz@streamunlimited.com> wrote:
>
> On Wed, Nov 11, 2020 at 06:25:45PM +0100, Nicolas Dechesne wrote:
> > On Wed, Nov 11, 2020 at 5:28 PM Quentin Schulz
> > <quentin.schulz@streamunlimited.com> wrote:
> > >
> > > Hi Paul,
> > >
> > > On Wed, Nov 11, 2020 at 04:07:53PM +0000, Paul Barker wrote:
> > > > After discussions on IRC with Ross we concluded that the `ross/mut`
> > > > branch shouldn't really be listed in the docs as it's more of a personal
> > > > test branch. Instead we should list the -next branches for
> > > > openembedded-core and poky.
> > > >
> > > > Signed-off-by: Paul Barker <pbarker@konsulko.com>
> > > > ---
> > > >  .../dev-manual/dev-manual-common-tasks.rst    | 35 ++++++++++++-------
> > > >  1 file changed, 23 insertions(+), 12 deletions(-)
> > > >
> > > > diff --git a/documentation/dev-manual/dev-manual-common-tasks.rst b/documentation/dev-manual/dev-manual-common-tasks.rst
> > > > index 27aacde60..698b27377 100644
> > > > --- a/documentation/dev-manual/dev-manual-common-tasks.rst
> > > > +++ b/documentation/dev-manual/dev-manual-common-tasks.rst
> > > > @@ -10665,18 +10665,29 @@ to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a
> > > >  section in the Yocto Project Overview and Concepts Manual for additional
> > > >  concepts on working in the Yocto Project development environment.
> > > >
> > > > -Two commonly used testing repositories exist for OpenEmbedded-Core:
> > > > -
> > > > --  *"ross/mut" branch:* The "mut" (master-under-test) tree exists in the
> > > > -   ``poky-contrib`` repository in the
> > > > -   :yocto_git:`Yocto Project source repositories <>`.
> > > > -
> > > > --  *"master-next" branch:* This branch is part of the main "poky"
> > > > -   repository in the Yocto Project source repositories.
> > > > -
> > > > -Maintainers use these branches to test submissions prior to merging
> > > > -patches. Thus, you can get an idea of the status of a patch based on
> > > > -whether the patch has been merged into one of these branches.
> > > > +Maintainers commonly use ``-next`` branches to test submissions prior to
> > > > +merging patches. Thus, you can get an idea of the status of a patch based on
> > > > +whether the patch has been merged into one of these branches. The commonly
> > > > +used testing branches for OpenEmbedded-Core are as follows:
> > > > +
> > > > +-  *openembedded-core "master-next" branch:* This branch is part of the
> > > > +   `openembedded-core <https://git.openembedded.org/openembedded-core/>`__
> > >
> > > Side note: should we add a :oe_git: directive as we already have :yocto_git:?

I'll see if I can add this directive and change the link.

> > >
> > > > +   repository on git.openembedded.org and contains proposed changes to the
> > > > +   core metadata.
> > > > +
> > > > +-  *poky "master-next" branch:* This branch is part of the
> > > > +   `poky <https://git.yoctoproject.org/cgit/cgit.cgi/poky/>`__
> > >
> > > :yocto_git:`poky </cgit/cgit.cgi/poky/>`

I'll change this.

> > >
> > > > +   repository on git.yoctoproject.org and combines proposed changes to
> > >
> > > Maybe s/git.yoctoproject.org/&YOCTO_GIT_URL;/ ? Not convinced though, no
> > > hard feeling if this is not taken into account.
> >
> > or :yocto_git:`/` like we do in other places? It would render as
> > https://git.yoctoproject.org/ , not git.yoctoproject.org, but I think
> > it's better, no?
> >
>
> +1 for the obvious, completely missed it.
>
> Though, now, not sure we need to state that it's from
> git.yoctoproject.org while actually giving a direct link to the poky
> repo a few words before?

Actually, yes, it's a little redundant. I'll simplify this text.

-- 
Paul Barker
Konsulko Group

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

[Paul Barker]

On Wed, 11 Nov 2020 at 16:39, 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>`

That's an easy fix.

>
> > +.. 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 ?

Yes that would be better. I didn't know a lot of these expressions
existed but they look very helpful.

-- 
Paul Barker
Konsulko Group