dev-manual-common-tasks: Fix refs to testing branches
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
@@ -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
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
@@ -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
PATCH 3/8 dev-manual-common-tasks: Tidy up patch submission process
In reply to Paul BarkerReduce 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
@@ -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
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
@@ -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
PATCH 5/8 dev-manual-common-tasks: Describe how to handle patch feedback
In reply to Paul BarkerThe 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
@@ -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
PATCH 6/8 dev-manual-common-tasks: Describe how to propose changes to stable branches
In reply to Paul BarkerThe 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
@@ -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
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.
Signed-off-by Paul Barker <[email protected]>--- .../dev-manual/dev-manual-common-tasks.rst | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+)documentation/dev-manual/dev-manual-common-tasks.rst +4
-0@@ -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
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.
Signed-off-by Paul Barker <[email protected]>--- .../dev-manual/dev-manual-common-tasks.rst | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+)documentation/dev-manual/dev-manual-common-tasks.rst +4
-0@@ -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 differsdocumentation/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
Re: [docs] [PATCH 6/8] dev-manual-common-tasks: Describe how to propose changes to stable branches
In reply to Quentin SchulzQuoted 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.
Signed-off-by Paul Barker <[email protected]>--- .../dev-manual/dev-manual-common-tasks.rst | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+)documentation/dev-manual/dev-manual-common-tasks.rst +0
-0@@ -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 differsdocumentation/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
PATCH 7/8 dev-manual-common-tasks: Re-order patch submission instructions
In reply to Paul BarkerNew 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
@@ -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
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.
Signed-off-by Paul Barker <[email protected]>--- .../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@@ -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
-0detailed 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
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.
Signed-off-by Paul Barker <[email protected]>--- .../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@@ -10776,11 +10776,110 @@ Preparing Changes for Submissiondocumentation/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
-0detailed 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 emaildocumentation/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 thanI 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``, ordocumentation/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 notDo 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
PATCH 8/8 documentation/README: Refer to top-level README for contributions
In reply to Paul BarkerThis 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
@@ -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
Quoted 7 lines · Paul Barker
After discussions on IRC with Ross we concluded that the
ross/mutbranch 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 <[email protected]>
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@@ -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
Quoted 11 lines · Paul Barker
Quoted 7 lines · Paul Barker
After discussions on IRC with Ross we concluded that the
ross/mutbranch 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 <[email protected]>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
Hi Paul,
Quoted 27 lines · Paul Barker
After discussions on IRC with Ross we concluded that the
ross/mutbranch 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 <[email protected]>--- .../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@@ -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
Quoted 50 lines · Quentin Schulz
Hi Paul,
Quoted 27 lines · Paul Barker
After discussions on IRC with Ross we concluded that the
ross/mutbranch 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 <[email protected]>--- .../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@@ -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 toMaybe 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
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/mutbranch 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 <[email protected]>--- .../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@@ -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 toMaybe 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
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/mutbranch 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 <[email protected]>--- .../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@@ -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 toMaybe 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