Contributor Guide updates
cover Contributor Guide updates
From: Michael Opdenacker <[email protected]>
Work in progress to update and improve the instructions for contributors.
Note that these commits are part of an incremental process. More useful details (such as configuring Git for git send-email) will be sent through later patches.
Michael Opdenacker (5):
contributor guide: call section "Reporting a defect"
contributor-guide: remove obsolete pkg-config guidelines contributor guide: remove unnecessary information about mailing lists
contributor-guide: clarification about patchtest contributor guide: update instructions for making and sharing changes
documentation/bsp-guide/bsp.rst | 2 +-
documentation/contributor-guide/index.rst | 4 +-
.../contributor-guide/recipe-style-guide.rst | 5 -
.../{submit-defect.rst => report-defect.rst} | 2 +-
.../{submit-change.rst => submit-changes.rst} | 145 +++++++++---------
documentation/dev-manual/debugging.rst | 4 +-
documentation/dev-manual/start.rst | 4 +-
documentation/dev-manual/vulnerabilities.rst | 2 +-
.../development-environment.rst | 6 +-
documentation/ref-manual/resources.rst | 2 +-
.../ref-manual/system-requirements.rst | 2 +-
11 files changed, 87 insertions(+), 91 deletions(-)
rename documentation/contributor-guide/{submit-defect.rst => report-defect.rst} (98%)
rename documentation/contributor-guide/{submit-change.rst => submit-changes.rst} (83%)Signature · 1 line
2.34.1
PATCH 1/5 contributor guide: call section "Reporting a defect"
From: Michael Opdenacker <[email protected]>
Instead of "Submitting a defect".
We all write bugs, and nobody needs documentation
support for doing so!
---
documentation/contributor-guide/index.rst | 2 +-
.../contributor-guide/{submit-defect.rst => report-defect.rst} | 2 +-
documentation/dev-manual/debugging.rst | 2 +-
documentation/ref-manual/resources.rst | 2 +-
documentation/ref-manual/system-requirements.rst | 2 +-
5 files changed, 5 insertions(+), 5 deletions(-)
rename documentation/contributor-guide/{submit-defect.rst => report-defect.rst} (98%)documentation/contributor-guide/index.rst +1 -1
@@ -19,7 +19,7 @@ this. :numbered: identify-component - submit-defect + report-defect recipe-style-guide submit-change
documentation/contributor-guide/report-defect.rst renamed from documentation/contributor-guide/submit-defect.rst +1 -1
@@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-2.0-UK -Submitting a Defect Against the Yocto Project and OpenEmbedded +Reporting a Defect Against the Yocto Project and OpenEmbedded ************************************************************** You can use the Yocto Project instance of
documentation/dev-manual/debugging.rst +1 -1
@@ -1235,7 +1235,7 @@ Here are some other tips that you might find useful: :yocto_bugs:`Bugzilla <>`. For information on how to submit a bug against the Yocto Project, see the Yocto Project Bugzilla :yocto_wiki:`wiki page </Bugzilla_Configuration_and_Bug_Tracking>` - and the ":doc:`../contributor-guide/submit-defect`" section. + and the ":doc:`../contributor-guide/report-defect`" section. .. note::
documentation/ref-manual/resources.rst +1 -1
@@ -45,7 +45,7 @@ your expectations). For a general procedure and guidelines on how to use Bugzilla to submit a bug against the Yocto Project, see the following: -- The ":doc:`../contributor-guide/submit-defect`" +- The ":doc:`../contributor-guide/report-defect`" section in the Yocto Project and OpenEmbedded Contributor Guide. - The Yocto Project :yocto_wiki:`Bugzilla wiki page </Bugzilla_Configuration_and_Bug_Tracking>`
documentation/ref-manual/system-requirements.rst +1 -1
@@ -134,7 +134,7 @@ tested by the &DISTRO; release ("&DISTRO_NAME;"), but no longer are: interested in hearing about your experience. For information on how to submit a bug, see the Yocto Project :yocto_wiki:`Bugzilla wiki page </Bugzilla_Configuration_and_Bug_Tracking>` - and the ":doc:`../contributor-guide/submit-defect`" + and the ":doc:`../contributor-guide/report-defect`" section in the Yocto Project and OpenEmbedded Contributor Guide. Required Packages for the Build Host
Signature · 1 line
2.34.1
PATCH 2/5 contributor-guide: remove obsolete pkg-config guidelines
In reply to [email protected]From: Michael Opdenacker <[email protected]>
They were coming from obsolete notes from the times when people directly created or modified .pc files from their recipes. Nobody should be doing that any more and keep this can be confusing.
--- documentation/contributor-guide/recipe-style-guide.rst | 5 ----- 1 file changed, 5 deletions(-)
documentation/contributor-guide/recipe-style-guide.rst +0 -5
@@ -255,8 +255,3 @@ Tips and Guidelines for Writing Recipes - Use :term:`BBCLASSEXTEND` instead of creating separate recipes such as ``-native`` and ``-nativesdk`` ones, whenever possible. This avoids having to maintain multiple recipe files at the same time. - -- Avoid manually mangling ``pkg-config`` ``.pc`` files. - Recipes using ``pkg-config`` should use variables to ensure they are correctly - relocatable and not need manual path correction in the recipe. -
Signature · 1 line
2.34.1
PATCH 3/5 contributor guide: remove unnecessary information about mailing lists
In reply to [email protected]From: Michael Opdenacker <[email protected]>
The mailing lists for sending code are sufficient!
--- documentation/contributor-guide/submit-change.rst | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-)
documentation/contributor-guide/submit-change.rst +4 -7
@@ -226,9 +226,7 @@ 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 ":ref:`contributor-guide/submit-change:finding a suitable mailing list`" -section above. For a description of all the available -mailing lists, see the ":ref:`Mailing Lists <resources-mailinglist>`" section in the -Yocto Project Reference Manual. +section above. Here is the general procedure on how to submit a patch through email without using the scripts once the steps in
@@ -369,10 +367,9 @@ have been followed: you can see who is responsible for the bulk of the changes against the file. - - *Examine the List of Mailing Lists:* For a list of the Yocto - Project and related mailing lists, see the ":ref:`Mailing - lists <resources-mailinglist>`" section in - the Yocto Project Reference Manual. + - *Find the Mailing List to Use:* See the + ":ref:`contributor-guide/submit-change:finding a suitable mailing list`" + section above. #. *Make a Pull Request:* Notify the maintainer or the mailing list that you have pushed a change by making a pull request.
Signature · 1 line
2.34.1
PATCH 4/5 contributor-guide: clarification about patchtest
In reply to [email protected]From: Michael Opdenacker <[email protected]>
- Highlight that patchtest still needs improving
- Fix reference to this tool
--- documentation/contributor-guide/submit-change.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
documentation/contributor-guide/submit-change.rst +2 -2
@@ -43,7 +43,7 @@ mailing list approach off-putting and would prefer a web-based GUI. Since we don’t believe that can work for us, the project is aiming to ensure `patchwork <https://patchwork.yoctoproject.org/>`__ is available to help track patch status and also looking at how tooling can provide more feedback to users -about patch status. We are looking at tools such as ``patchtest`` to +about patch status. We are looking at improving tools such as ``patchtest`` to test user contributions before they hit the mailing lists and also at better documenting how to use such workflows since we recognise that whilst this was common knowledge a decade ago, it might not be as familiar now.
@@ -299,7 +299,7 @@ The Yocto Project uses a `Patchwork instance <https://patchwork.yoctoproject.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 +notified by ``patchtest`` if such mistakes are found. This process helps to reduce the burden of patch review on maintainers. .. note::
Signature · 1 line
2.34.1
PATCH 5/5 contributor guide: update instructions for making and sharing changes
In reply to [email protected]From: Michael Opdenacker <[email protected]>
- Shifting the focus to multiple changes instead of just one
- Advising to create a branch for changes
- Removing unnecessary or too verbose explanations
- Adding useful resources and examples
---
documentation/bsp-guide/bsp.rst | 2 +-
documentation/contributor-guide/index.rst | 2 +-
.../{submit-change.rst => submit-changes.rst} | 132 +++++++++---------
documentation/dev-manual/debugging.rst | 2 +-
documentation/dev-manual/start.rst | 4 +-
documentation/dev-manual/vulnerabilities.rst | 2 +-
.../development-environment.rst | 6 +-
7 files changed, 77 insertions(+), 73 deletions(-)
rename documentation/contributor-guide/{submit-change.rst => submit-changes.rst} (85%)documentation/bsp-guide/bsp.rst +1 -1
@@ -927,7 +927,7 @@ Yocto Project: - The name and contact information for the BSP layer maintainer. This is the person to whom patches and questions should be sent. For information on how to find the right person, see the - :doc:`../contributor-guide/submit-change` section in the Yocto Project and + :doc:`../contributor-guide/submit-changes` section in the Yocto Project and OpenEmbedded Contributor Guide. - Instructions on how to build the BSP using the BSP layer.
documentation/contributor-guide/index.rst +1 -1
@@ -21,6 +21,6 @@ this. identify-component report-defect recipe-style-guide - submit-change + submit-changes .. include:: /boilerplate.rst
documentation/contributor-guide/submit-changes.rst renamed from documentation/contributor-guide/submit-change.rst +68 -64
229 lines not on this page · raw message
documentation/dev-manual/debugging.rst +1 -1
@@ -879,7 +879,7 @@ The build should work without issue. As with all solved problems, if they originated upstream, you need to submit the fix for the recipe in OE-Core and upstream so that the problem is taken care of at its source. See the -":doc:`../contributor-guide/submit-change`" section for more information. +":doc:`../contributor-guide/submit-changes`" section for more information. Debugging With the GNU Project Debugger (GDB) Remotely ======================================================
documentation/dev-manual/start.rst +2 -2
@@ -246,13 +246,13 @@ particular working environment and set of practices. - The Yocto Project community encourages you to send patches to the project to fix bugs or add features. If you do submit patches, follow the project commit guidelines for writing good commit - messages. See the ":doc:`../contributor-guide/submit-change`" + messages. See the ":doc:`../contributor-guide/submit-changes`" section in the Yocto Project and OpenEmbedded Contributor Guide. - Send changes to the core sooner than later as others are likely to run into the same issues. For some guidance on mailing lists to use, see the lists in the - ":ref:`contributor-guide/submit-change:finding a suitable mailing list`" + ":ref:`contributor-guide/submit-changes:finding a suitable mailing list`" section. For a description of the available mailing lists, see the ":ref:`resources-mailinglist`" section in the Yocto Project Reference Manual.
documentation/dev-manual/vulnerabilities.rst +1 -1
@@ -22,7 +22,7 @@ issues may be impacting Poky and OE-Core. It is up to the maintainers, users, contributors and anyone interested in the issues to investigate and possibly fix them by updating software components to newer versions or by applying patches to address them. It is recommended to work with Poky and OE-Core upstream maintainers and submit -patches to fix them, see ":doc:`../contributor-guide/submit-change`" for details. +patches to fix them, see ":doc:`../contributor-guide/submit-changes`" for details. Vulnerability check at build time =================================
documentation/overview-manual/development-environment.rst +3 -3
@@ -264,7 +264,7 @@ push them into the "contrib" area and subsequently request that the maintainer include them into an upstream branch. This process is called "submitting a patch" or "submitting a change." For information on submitting patches and changes, see the -":doc:`../contributor-guide/submit-change`" section in the Yocto Project +":doc:`../contributor-guide/submit-changes`" section in the Yocto Project and OpenEmbedded Contributor Guide. In summary, there is a single point of entry for changes into the
@@ -330,7 +330,7 @@ Book <https://book.git-scm.com>`__. release to facilitate this workflow. You can find these scripts in the ``scripts`` folder of the :term:`Source Directory`. For information on how to use these scripts, see the - ":ref:`contributor-guide/submit-change:using scripts to push a change upstream and request a pull`" + ":ref:`contributor-guide/submit-changes:using scripts to push a change upstream and request a pull`" section in the Yocto Project and OpenEmbedded Contributor Guide. - *Patch Workflow:* This workflow allows you to notify the maintainer
@@ -339,7 +339,7 @@ Book <https://book.git-scm.com>`__. this type of change, you format the patch and then send the email using the Git commands ``git format-patch`` and ``git send-email``. For information on how to use these scripts, see the - ":doc:`../contributor-guide/submit-change`" section in the Yocto Project + ":doc:`../contributor-guide/submit-changes`" section in the Yocto Project and OpenEmbedded Contributor Guide. Git
Signature · 1 line
2.34.1