Skip to contentSkip to conversation

Contributor Guide updates

PATCH New [email protected] 1 participant 6 messages Aug 11, 2023

lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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
index 7a39f994e2..8fa65045a3 100644
@@ -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
similarity index 98%
rename from documentation/contributor-guide/submit-defect.rst
rename to documentation/contributor-guide/report-defect.rst
index 527ffb2dc0..8ef133b842 100644
@@ -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
index 3a8d5080ce..890578cc05 100644
@@ -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
index 324d1fad10..8c3726e83b 100644
@@ -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
index 9ae7b4e63b..66ab65d2b7 100644
@@ -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
#2 lore raw

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
index 35ffbc61ef..a0d513e8e9 100644
@@ -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
#3 lore raw

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
index 1327b2854c..3fd2b049cf 100644
@@ -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
#4 lore raw

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
index 3fd2b049cf..6bee423bfb 100644
@@ -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
#5 lore raw

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
index 52a07cfcb0..3be314bcf6 100644
@@ -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
index 8fa65045a3..a832169455 100644
@@ -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
index 890578cc05..fea2cb30a1 100644
@@ -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
index 372959d9ed..88afa27ad5 100644
@@ -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
index 297789dae6..71111bb3e2 100644
@@ -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
index 55f34c18da..262d5cb203 100644
@@ -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