Skip to contentSkip to conversation

dev-manual-common-tasks: Fix refs to testing branches

PATCH Superseded Paul Barker 4 participants 19 messages Nov 11, 2020 – Nov 18, 2020

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

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

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.

---
 .../dev-manual/dev-manual-common-tasks.rst    | 35 ++++++++++++-------
 1 file changed, 23 insertions(+), 12 deletions(-)
documentation/dev-manual/dev-manual-common-tasks.rst +23 -12
index 27aacde60..698b27377 100644
@@ -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::
 
Signature · 1 line
2.20.1
#1 lore raw

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

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.

---
 .../dev-manual/dev-manual-common-tasks.rst    | 23 +++++++++++--------
 1 file changed, 13 insertions(+), 10 deletions(-)
documentation/dev-manual/dev-manual-common-tasks.rst +13 -10
index 698b27377..2f28cce62 100644
@@ -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
 =====================
 
Signature · 1 line
2.20.1
#2 lore raw

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

In reply to 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.

---
 .../dev-manual/dev-manual-common-tasks.rst    | 63 ++++++++-----------
 1 file changed, 25 insertions(+), 38 deletions(-)
documentation/dev-manual/dev-manual-common-tasks.rst +25 -38
index 2f28cce62..641ca8539 100644
@@ -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::
Signature · 1 line
2.20.1
#3 lore raw

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

In reply to Paul Barker
---
 documentation/dev-manual/dev-manual-common-tasks.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
documentation/dev-manual/dev-manual-common-tasks.rst +2 -2
index 641ca8539..b34602e16 100644
@@ -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::
 
Signature · 1 line
2.20.1
#4 lore raw

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

In reply to 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.

---
 .../dev-manual/dev-manual-common-tasks.rst    | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)
documentation/dev-manual/dev-manual-common-tasks.rst +22 -0
index b34602e16..0a3ab8241 100644
@@ -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
 =====================
 
Signature · 1 line
2.20.1
#5 lore raw

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

In reply to 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.

---
 .../dev-manual/dev-manual-common-tasks.rst    | 55 +++++++++++++++++++
 1 file changed, 55 insertions(+)
documentation/dev-manual/dev-manual-common-tasks.rst +55 -0
index 0a3ab8241..e923ce834 100644
@@ -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
 =====================
 
Signature · 1 line
2.20.1
#6 lore raw

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

Hi Paul,

Quoted 25 lines · 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.

---
 .../dev-manual/dev-manual-common-tasks.rst    | 55 +++++++++++++++++++
 1 file changed, 55 insertions(+)
documentation/dev-manual/dev-manual-common-tasks.rst +4 -0
index 0a3ab8241..e923ce834 100644
@@ -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

documentation/dev-manual/dev-manual-common-tasks.rst Lastly please ensure that you also test your revised changes. In particular · line 11021

Quoted 10 lines
documentation/dev-manual/dev-manual-common-tasks.rst +10 -0
+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>

Quoted 30 lines
documentation/dev-manual/dev-manual-common-tasks.rst +30 -0
+.. 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

documentation/dev-manual/dev-manual-common-tasks.rst Lastly please ensure that you also test your revised changes. In particular · line 11061

Quoted 10 lines
documentation/dev-manual/dev-manual-common-tasks.rst +10 -0
+      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

#7 lore raw

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

Quoted 76 lines · Quentin Schulz

Hi Paul,

Quoted 25 lines · 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.

---
 .../dev-manual/dev-manual-common-tasks.rst    | 55 +++++++++++++++++++
 1 file changed, 55 insertions(+)
documentation/dev-manual/dev-manual-common-tasks.rst +4 -0
index 0a3ab8241..e923ce834 100644
@@ -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

documentation/dev-manual/dev-manual-common-tasks.rst Lastly please ensure that you also test your revised changes. In particular · line 11021

Quoted 10 lines
documentation/dev-manual/dev-manual-common-tasks.rst +10 -0
+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>

Quoted 34 lines
documentation/dev-manual/dev-manual-common-tasks.rst +34 -0
+.. 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
Quoted 8 lines

documentation/dev-manual/dev-manual-common-tasks.rst Lastly please ensure that you also test your revised changes. In particular · line 11061

Quoted 6 lines
documentation/dev-manual/dev-manual-common-tasks.rst +6 -0
+      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..

Quoted 6 lines

Thanks,
Quentin

#8 lore raw

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

In reply to Quentin Schulz
Quoted 25 lines · Quentin Schulz

Hi Paul,

Quoted 21 lines · 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.

---
 .../dev-manual/dev-manual-common-tasks.rst    | 55 +++++++++++++++++++
 1 file changed, 55 insertions(+)
documentation/dev-manual/dev-manual-common-tasks.rst +0 -0
index 0a3ab8241..e923ce834 100644
@@ -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.
 
Quoted 16 lines
Quoted 4 lines
documentation/dev-manual/dev-manual-common-tasks.rst +4 -0
+Submitting Changes to Stable Release Branches
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The process for proposing changes to a Yocto Project stable branch differs

documentation/dev-manual/dev-manual-common-tasks.rst Lastly please ensure that you also test your revised changes. In particular · line 11021

Quoted 10 lines
documentation/dev-manual/dev-manual-common-tasks.rst +10 -0
+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.

Quoted 35 lines
Quoted 35 lines
documentation/dev-manual/dev-manual-common-tasks.rst +34 -0
+.. 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
Quoted 8 lines

documentation/dev-manual/dev-manual-common-tasks.rst Lastly please ensure that you also test your revised changes. In particular · line 11061

Quoted 6 lines
documentation/dev-manual/dev-manual-common-tasks.rst +6 -0
+      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.

Signature · 2 lines
Paul Barker
Konsulko Group
#9 lore raw

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

In reply to 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.

---
 .../dev-manual/dev-manual-common-tasks.rst    | 196 +++++++++---------
 1 file changed, 99 insertions(+), 97 deletions(-)
documentation/dev-manual/dev-manual-common-tasks.rst +99 -97
index e923ce834..cde1b80d1 100644
@@ -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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
Signature · 1 line
2.20.1
#10 lore raw

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

Hi Paul,

Quoted 21 lines · 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.

---
 .../dev-manual/dev-manual-common-tasks.rst    | 196 +++++++++---------
 1 file changed, 99 insertions(+), 97 deletions(-)
documentation/dev-manual/dev-manual-common-tasks.rst +0 -0
index e923ce834..cde1b80d1 100644
@@ -10776,11 +10776,110 @@ Preparing Changes for Submission
 

documentation/dev-manual/dev-manual-common-tasks.rst Preparing Changes for Submission · line 10786

Quoted 10 lines
documentation/dev-manual/dev-manual-common-tasks.rst +8 -0
          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>.

Quoted 5 lines
documentation/dev-manual/dev-manual-common-tasks.rst +5 -0
+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

documentation/dev-manual/dev-manual-common-tasks.rst Preparing Changes for Submission · line 10801

Quoted 10 lines
documentation/dev-manual/dev-manual-common-tasks.rst +10 -0
+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.

documentation/dev-manual/dev-manual-common-tasks.rst Preparing Changes for Submission · line 10805

Quoted 4 lines
documentation/dev-manual/dev-manual-common-tasks.rst +4 -0
+
+      $ git format-patch -1
+
+   or ::

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

documentation/dev-manual/dev-manual-common-tasks.rst Preparing Changes for Submission · line 10814

Quoted 9 lines
documentation/dev-manual/dev-manual-common-tasks.rst +9 -0
+
+      $ 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.

Quoted 24 lines
documentation/dev-manual/dev-manual-common-tasks.rst +24 -0
+   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

documentation/dev-manual/dev-manual-common-tasks.rst Preparing Changes for Submission · line 10848

Quoted 10 lines
documentation/dev-manual/dev-manual-common-tasks.rst +10 -0
+   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?

Quoted 18 lines
documentation/dev-manual/dev-manual-common-tasks.rst +18 -0
+   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::
+

documentation/dev-manual/dev-manual-common-tasks.rst Preparing Changes for Submission · line 10876

Quoted 10 lines
documentation/dev-manual/dev-manual-common-tasks.rst +5 -0
+   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+?)

Quoted 103 lines
documentation/dev-manual/dev-manual-common-tasks.rst +6 -90
+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.

documentation/dev-manual/dev-manual-common-tasks.rst been followed: · line 10990

Quoted 10 lines
documentation/dev-manual/dev-manual-common-tasks.rst +0 -7
-
-.. 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

#11 lore raw

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

Quoted 273 lines · Quentin Schulz

Hi Paul,

Quoted 21 lines · 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.

---
 .../dev-manual/dev-manual-common-tasks.rst    | 196 +++++++++---------
 1 file changed, 99 insertions(+), 97 deletions(-)
documentation/dev-manual/dev-manual-common-tasks.rst +0 -0
index e923ce834..cde1b80d1 100644
@@ -10776,11 +10776,110 @@ Preparing Changes for Submission
 

documentation/dev-manual/dev-manual-common-tasks.rst Preparing Changes for Submission · line 10786

Quoted 10 lines
documentation/dev-manual/dev-manual-common-tasks.rst +8 -0
          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>.

Quoted 5 lines
documentation/dev-manual/dev-manual-common-tasks.rst +5 -0
+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

documentation/dev-manual/dev-manual-common-tasks.rst Preparing Changes for Submission · line 10801

Quoted 10 lines
documentation/dev-manual/dev-manual-common-tasks.rst +10 -0
+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.

documentation/dev-manual/dev-manual-common-tasks.rst Preparing Changes for Submission · line 10805

Quoted 4 lines
documentation/dev-manual/dev-manual-common-tasks.rst +4 -0
+
+      $ git format-patch -1
+
+   or ::

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

documentation/dev-manual/dev-manual-common-tasks.rst Preparing Changes for Submission · line 10814

Quoted 9 lines
documentation/dev-manual/dev-manual-common-tasks.rst +9 -0
+
+      $ 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.

Quoted 24 lines
documentation/dev-manual/dev-manual-common-tasks.rst +24 -0
+   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

documentation/dev-manual/dev-manual-common-tasks.rst Preparing Changes for Submission · line 10848

Quoted 10 lines
documentation/dev-manual/dev-manual-common-tasks.rst +10 -0
+   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?

Quoted 18 lines
documentation/dev-manual/dev-manual-common-tasks.rst +18 -0
+   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::
+

documentation/dev-manual/dev-manual-common-tasks.rst Preparing Changes for Submission · line 10876

Quoted 10 lines
documentation/dev-manual/dev-manual-common-tasks.rst +5 -0
+   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+?)

Quoted 103 lines
documentation/dev-manual/dev-manual-common-tasks.rst +6 -90
+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.

documentation/dev-manual/dev-manual-common-tasks.rst been followed: · line 10990

Quoted 10 lines
documentation/dev-manual/dev-manual-common-tasks.rst +0 -7
-
-.. 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 :)

Quoted 1 line

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,

Signature · 2 lines
Paul Barker
Konsulko Group
#12 lore raw

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

In reply to Paul Barker

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

---
 documentation/README | 6 ++++++
 1 file changed, 6 insertions(+)
documentation/README +6 -0
index 534ae66f8..5beed2517 100644
@@ -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.
Signature · 1 line
2.20.1
#13 lore raw
In reply to Paul Barker
Quoted 7 lines · 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.

Cc Ross.
Quoted 53 lines
---
 .../dev-manual/dev-manual-common-tasks.rst    | 35 ++++++++++++-------
 1 file changed, 23 insertions(+), 12 deletions(-)
documentation/dev-manual/dev-manual-common-tasks.rst +23 -13
index 27aacde60..698b27377 100644
@@ -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

Signature · 2 lines
Paul Barker
Konsulko Group
#14 lore raw
Quoted 11 lines · Paul Barker
Quoted 7 lines · 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.

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

#15 lore raw
In reply to Paul Barker

Hi Paul,

Quoted 27 lines · 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.

---
 .../dev-manual/dev-manual-common-tasks.rst    | 35 ++++++++++++-------
 1 file changed, 23 insertions(+), 12 deletions(-)
documentation/dev-manual/dev-manual-common-tasks.rst +0 -9
index 27aacde60..698b27377 100644
@@ -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.
-

documentation/dev-manual/dev-manual-common-tasks.rst to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a · line 10674

Quoted 10 lines
documentation/dev-manual/dev-manual-common-tasks.rst +7 -3
-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:?

documentation/dev-manual/dev-manual-common-tasks.rst to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a · line 10679

Quoted 5 lines
documentation/dev-manual/dev-manual-common-tasks.rst +5 -0
+   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/>

documentation/dev-manual/dev-manual-common-tasks.rst to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a · line 10680

Quoted 1 line
documentation/dev-manual/dev-manual-common-tasks.rst +1 -0
+   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

#16 lore raw
Quoted 50 lines · Quentin Schulz

Hi Paul,

Quoted 27 lines · 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.

---
 .../dev-manual/dev-manual-common-tasks.rst    | 35 ++++++++++++-------
 1 file changed, 23 insertions(+), 12 deletions(-)
documentation/dev-manual/dev-manual-common-tasks.rst +0 -9
index 27aacde60..698b27377 100644
@@ -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.
-

documentation/dev-manual/dev-manual-common-tasks.rst to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a · line 10674

Quoted 10 lines
documentation/dev-manual/dev-manual-common-tasks.rst +7 -3
-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:?

documentation/dev-manual/dev-manual-common-tasks.rst to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a · line 10679

Quoted 5 lines
documentation/dev-manual/dev-manual-common-tasks.rst +5 -0
+   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/>`__
Quoted 6 lines

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

documentation/dev-manual/dev-manual-common-tasks.rst to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a · line 10680

Quoted 1 line
documentation/dev-manual/dev-manual-common-tasks.rst +1 -0
+   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?

Quoted 6 lines

Thanks,
Quentin

#17 lore raw
Quoted 54 lines · Nicolas Dechesne
Quoted 52 lines · Quentin Schulz

Hi Paul,

Quoted 27 lines · 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.

---
 .../dev-manual/dev-manual-common-tasks.rst    | 35 ++++++++++++-------
 1 file changed, 23 insertions(+), 12 deletions(-)
documentation/dev-manual/dev-manual-common-tasks.rst +0 -9
index 27aacde60..698b27377 100644
@@ -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.
-

documentation/dev-manual/dev-manual-common-tasks.rst to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a · line 10674

Quoted 10 lines
documentation/dev-manual/dev-manual-common-tasks.rst +7 -3
-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:?

documentation/dev-manual/dev-manual-common-tasks.rst to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a · line 10679

Quoted 5 lines
documentation/dev-manual/dev-manual-common-tasks.rst +5 -0
+   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/>

Quoted 9 lines
Quoted 4 lines

documentation/dev-manual/dev-manual-common-tasks.rst to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a · line 10680

Quoted 1 line
documentation/dev-manual/dev-manual-common-tasks.rst +1 -0
+   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

#18 lore raw
Quoted 39 lines · Quentin Schulz
Quoted 37 lines · Nicolas Dechesne
Quoted 35 lines · Quentin Schulz

Hi Paul,

Quoted 31 lines · 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.

---
 .../dev-manual/dev-manual-common-tasks.rst    | 35 ++++++++++++-------
 1 file changed, 23 insertions(+), 12 deletions(-)
documentation/dev-manual/dev-manual-common-tasks.rst +1 -12
index 27aacde60..698b27377 100644
@@ -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
Quoted 8 lines
Quoted 8 lines
Quoted 8 lines

documentation/dev-manual/dev-manual-common-tasks.rst to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a · line 10674

Quoted 6 lines
documentation/dev-manual/dev-manual-common-tasks.rst +6 -0
+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.

Quoted 8 lines
Quoted 8 lines
Quoted 8 lines

documentation/dev-manual/dev-manual-common-tasks.rst to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a · line 10679

Quoted 6 lines
documentation/dev-manual/dev-manual-common-tasks.rst +5 -0
+   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.

Quoted 11 lines
Quoted 10 lines
Quoted 5 lines

documentation/dev-manual/dev-manual-common-tasks.rst to a contribution repository that is upstream. See the ":ref:`gs-git-workflows-a · line 10680

Quoted 2 lines
documentation/dev-manual/dev-manual-common-tasks.rst +1 -0
+   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?

Quoted 5 lines

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

Signature · 2 lines
Paul Barker
Konsulko Group