Skip to contentSkip to conversation

doc: sending_patches.rst: Incorporate the old "Patches" wiki content

PATCH In review Tom Rini 2 participants 5 messages Aug 29, 2022 – Aug 30, 2022

lore
Share & tools
lore

Tom Rini

author
#0 lore raw

PATCH 1/3 doc: sending_patches.rst: Incorporate the old "Patches" wiki content

Import as-is much of the old "Patches" wiki page to the current sending_patches.rst file. This means we need to move patman to being included in the higher level ToC and add a reference for "Custodians" in the process document. A very minimal amount of content changing and rewording is done here as part of the import, in order to make the conversion easier.

Cc Heinrich Schuchardt <[email protected]>
---
 doc/develop/index.rst           |   1 +
 doc/develop/process.rst         |   2 +
 doc/develop/sending_patches.rst | 503 +++++++++++++++++++++++++++++++-
 3 files changed, 503 insertions(+), 3 deletions(-)
doc/develop/index.rst +1 -0
index f7ee09db2467..72332f7da6dd 100644
@@ -11,6 +11,7 @@ General
 
    codingstyle
    designprinciples
+   patman
    process
    release_cycle
    system_configuration
doc/develop/process.rst +2 -0
index 388945cf9bb9..6a18a8104aa2 100644
@@ -108,6 +108,8 @@ Differences to the Linux Development Process
   In U-Boot, ``"-rc1"`` will only be released after all (or at least most of
   the) patches that were submitted during the merge window have been applied.
 
+.. _custodians:
+
 Custodians
 ----------
 
doc/develop/sending_patches.rst +500 -3

514 lines not on this page · raw message

Signature · 1 line
2.25.1
author
#1 lore raw

PATCH 2/3 doc: process, sending_patches: Update and correct the old "Patches" content

- Use gender-neutral language to refer to the user, consistently.
- Reference the checkpatch document.
- Move the section on commit message tags to the process document and reference this in sending_patches.rst.
- Reword the custodian workflow process section to refer to this new section, integrate some of the wording from there in this new section.
- Update the comment about GPLv2 applying to August 2022, to be clear this still is correct.
- Reword the section about MAKEALL to talk about local build testing and link to the CI document.
- Reference the system_configuration document for the note about modifying existing code.
- Reword the patchwork flow section.

Cc Heinrich Schuchardt <[email protected]>
---
 doc/develop/process.rst         |  85 ++++++++++++++++++----
 doc/develop/sending_patches.rst | 125 +++++++++-----------------------
 2 files changed, 104 insertions(+), 106 deletions(-)
doc/develop/process.rst +71 -14
index 6a18a8104aa2..0fa0143bf377 100644
@@ -129,31 +129,88 @@ patch, these should leave no doubt if they were just comments and the
 patch will be accepted anyway, or if the patch should be
 reworked/resubmitted, or if it was rejected.
 
-Work flow of a Custodian
+Review Process, Git Tags
 ------------------------
 
-The normal flow of work in the U-Boot development process will look
-like this:
+There are a number of *git tags* that are used to document the origin and the
+processing of patches on their way into the mainline U-Boot code. The following
+is an attempt to document how these are usually handled in the U-Boot project.
+
+In general, we try to follow the established procedures from other projects,
+especially the Linux kernel, but there may be smaller differences. For
+reference, see the Linux kernel's `Submitting patches
+<https://www.kernel.org/doc/html/latest/process/submitting-patches.html>`_
+document.
 
-#. A developer submits a patch via e-mail to the u-boot mailing list.  In
-   U-Boot, we make use of the `Developer Certificate of Origin
-   <https://developercertificate.org/>`_ that is common in other projects such
-   as the Linux kernel.  Following this and adding a ``Signed-off-by:`` line
-   that contains the developer's name and email address is required.
+.. _dco:
+
+* Signed-off-by: the *Signed-off-by:* is a line at the end of the commit
+  message by which the signer certifies that they were involved in the development
+  of the patch and that they accept the `Developer Certificate of Origin
+  <https://developercertificate.org/>`_. Following this and adding a
+  ``Signed-off-by:`` line that contains the developer's name and email address
+  is required.
+
+   * Please note that in U-Boot, we do not add a ``Signed-off-by`` tag if we
+     just pass on a patch without any changes.
 
    * Please note that when importing code from other projects you must say
      where it comes from, and what revision you are importing. You must not
      however copy ``Signed-off-by`` or other tags.
 
-#. Everybody who can is invited to review and test the changes.  Typically, we
-   follow the same guidelines as the Linux kernel for `Acked-by
-   <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#when-to-use-acked-by-cc-and-co-developed-by>`_
-   as well as `Reviewed-by
-   <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes>`_
-   and similar additional tags.
+* Everybody who can is invited to review and test the changes. Typically, we
+  follow the same guidelines as the Linux kernel for `Acked-by
+  <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#when-to-use-acked-by-cc-and-co-developed-by>`_
+  as well as `Reviewed-by
+  <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes>`_
+  and similar additional tags.
+
+* Reviewed-by: The patch has been reviewed and found acceptible according to
+  the `Reveiwer's statement of oversight
+  <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#reviewer-s-statement-of-oversight>`_.
+  A *Reviewed-by:* tag is a statement of opinion that the patch is an
+  appropriate modification of the code without any remaining serious technical
+  issues. Any interested reviewer (who has done the work) can offer a
+  *Reviewed-by:* tag for a patch.
+
+* Acked-by: If a person was not directly involved in the preparation or
+  handling of a patch but wishes to signify and record their approval of it
+  then they can arrange to have an *Acked-by:* line added to the patch's
+  changelog.
+
+* Tested-by: A *Tested-by:* tag indicates that the patch has been successfully
+  tested (in some environment) by the person named. Andrew Morton: "I think
+  it's very useful information to have. For a start, it tells you who has the
+  hardware and knows how to build a kernel. So if you're making a change to a
+  driver and want it tested, you can troll the file's changelog looking for
+  people who might be able to help."
+
+* Reported-by: If this patch fixes a problem reported by somebody else,
+  consider adding a *Reported-by:* tag to credit the reporter for their
+  contribution. Please note that this tag should not be added without the
+  reporter's permission, especially if the problem was not reported in a public
+  forum.
+
+* Cc: If a person should have the opportunity to comment on a patch, you may
+  optionally add a *Cc:* tag to the patch. Git tools (git send-email) will then
+  automatically arrange that they receives a copy of the patch when you submit it
+  to the mainling list. This is the only tag which might be added without an
+  explicit action by the person it names. This tag documents that potentially
+  interested parties have been included in the discussion.
+  For example, when your change affects a specific board or driver, then makes
+  a lot of sense to put the respective maintainer of this code on Cc:
+
+Work flow of a Custodian
+------------------------
+
+The normal flow of work in the U-Boot development process will look
+like this:
 
 #. The responsible custodian inspects this patch, especially for:
 
+   #. The commit message is useful, descriptive and makes correct and
+      appropraite usage of required *git tags*.
+
    #. :doc:`codingstyle`
 
    #. Basic logic:
doc/develop/sending_patches.rst +33 -92

207 lines not on this page · raw message

Signature · 1 line
2.25.1
author
#2 lore raw

PATCH 3/3 github: Update PR template for new "Patches" content

In reply to Tom Rini

The old "Patches" wiki page is not available anymore. Now that the content has been integrated with the submitting_patches document, reference that instead.

---
 .github/pull_request_template.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
.github/pull_request_template.md +1 -1
index ae91252a00bb..772810460c50 100644
@@ -1,6 +1,6 @@
 Please do not submit a Pull Request via github.  Our project makes use of
 mailing lists for patch submission and review.  For more details please
-see https://www.denx.de/wiki/U-Boot/Patches
+see https://u-boot.readthedocs.io/en/latest/develop/sending_patches.html
 
 The only exception to this is in order to trigger a CI loop on Azure prior
 to posting of patches.
Signature · 1 line
2.25.1
Reviewed-by on v1 3/3
#3 lore raw

Re: [PATCH 3/3] github: Update PR template for new "Patches" content

Quoted 9 lines · Tom Rini

The old "Patches" wiki page is not available anymore. Now that the content has been integrated with the submitting_patches document, reference that instead.

---
 .github/pull_request_template.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Quoted 16 lines
.github/pull_request_template.md +1 -2
index ae91252a00bb..772810460c50 100644
@@ -1,6 +1,6 @@
 Please do not submit a Pull Request via github.  Our project makes use of
 mailing lists for patch submission and review.  For more details please
-see https://www.denx.de/wiki/U-Boot/Patches
+see https://u-boot.readthedocs.io/en/latest/develop/sending_patches.html
 
 The only exception to this is in order to trigger a CI loop on Azure prior
 to posting of patches.
--

2.25.1

Reviewed-by on v1 1/3
#4 lore raw
In reply to Tom Rini
Quoted 8 lines · Tom Rini

Import as-is much of the old "Patches" wiki page to the current sending_patches.rst file. This means we need to move patman to being included in the higher level ToC and add a reference for "Custodians" in the process document. A very minimal amount of content changing and rewording is done here as part of the import, in order to make the conversion easier.

Quoted 7 lines
Cc Heinrich Schuchardt <[email protected]>
---
 doc/develop/index.rst           |   1 +
 doc/develop/process.rst         |   2 +
 doc/develop/sending_patches.rst | 503 +++++++++++++++++++++++++++++++-
 3 files changed, 503 insertions(+), 3 deletions(-)