[PATCH 2/3] doc: process, sending_patches: Update and correct the old "Patches" content
Tom Rini
trini at konsulko.com
Mon Aug 29 18:59:34 CEST 2022
- 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 <xypron.glpk at gmx.de>
Signed-off-by: Tom Rini <trini at konsulko.com>
---
doc/develop/process.rst | 85 ++++++++++++++++++----
doc/develop/sending_patches.rst | 125 +++++++++-----------------------
2 files changed, 104 insertions(+), 106 deletions(-)
diff --git a/doc/develop/process.rst b/doc/develop/process.rst
index 6a18a8104aa2..0fa0143bf377 100644
--- a/doc/develop/process.rst
+++ b/doc/develop/process.rst
@@ -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:
diff --git a/doc/develop/sending_patches.rst b/doc/develop/sending_patches.rst
index 506501203a99..173075687e9f 100644
--- a/doc/develop/sending_patches.rst
+++ b/doc/develop/sending_patches.rst
@@ -11,7 +11,7 @@ to oversee the consequences of a specific change to all architectures.
Discussing concepts early can help you to avoid spending effort on code which,
when submitted as a patch, might be rejected and/or will need lots of rework
because it does not fit for some reason. Early peer review is an important
-resource - use it.
+resource - use it. Being familiar with the :doc:`process` is also important.
A good introduction how to prepare for submitting patches can be found in the
LWN article `How to Get Your Change Into the Linux Kernel
@@ -53,7 +53,7 @@ General Patch Submission Rules
done in separate patches marked as ``cosmetic``. This separation of functional
and cosmetic changes greatly facilitates the review process.
-* Some comments on running ``checkpatch.pl``:
+* Some comments on running :doc:`checkpatch.pl <checkpatch>`:
* Checkpatch is a tool that can help you find some style problems, but is
imperfect, and the things it complains about are of varying importance.
@@ -134,7 +134,8 @@ Attributing Code, Copyrights, Signing
-------------------------------------
* Sign your changes, i. e. add a *Signed-off-by:* line to the message body.
- This can be automated by using ``git commit -s``.
+ This can be automated by using ``git commit -s``. Please see the
+ :ref:`Developer Certificate of Origin <dco>` section for more details here.
* If you change or add *significant* parts to a file, then please make sure to
add your copyright to that file, for example like this::
@@ -221,7 +222,8 @@ log messages.
description.
* End your log message with S.O.B. (Signed-off-by) line. This is done
- automatically when you use ``git commit -s``.
+ automatically when you use ``git commit -s``. Please see the
+ :ref:`Developer Certificate of Origin <dco>` section for more details here.
* Keep EVERY line under 72 characters. That is, your message should be
line-wrapped with line-feeds. However, don't get carried away and wrap it too
@@ -301,34 +303,28 @@ Notes
1. U-Boot is Free Software that can redistributed and/or modified under the
terms of the `GNU General Public License
- <http://www.fsf.org/licensing/licenses/gpl.html>`_ (GPL). Currently (July
- 2009) version 2 of the GPL applies. Please see :download:`Licensing
+ <http://www.fsf.org/licensing/licenses/gpl.html>`_ (GPL). Currently (August
+ 2022) version 2 of the GPL applies. Please see :download:`Licensing
<../../Licenses/README>` for details. To allow that later versions of U-Boot
may be released under a later version of the GPL, all new code that gets
added to U-Boot shall use a "GPL-2.0+" SPDX-License-Identifier.
2. All code must follow the :doc:`codingstyle` requirements.
-3. Before sending the patch, you *must* run the ``MAKEALL`` script on your
- patched source tree and make sure that no errors or warnings are reported
- for any of the boards. Well, at least not any more warnings than without
- your patch. It is *strongly* recommended to verify that out-of-tree
- building (with ``-O`` _make_ option resp. ``BUILD_DIR`` environment
- variable) is still working. For example, run ``BUILD_DIR=/tmp/u-boot-build ./MAKEALL``.
- Please also run ``MAKEALL`` for *at least one other architecture* than the one
- you made your modifications in.
+3. Before sending the patch, you *must* run some form of local testing.
+ Submitting a patch that does not build or function correct is a mistake. For
+ non-trivial patches, either building a number of platforms locally or making
+ use of :doc:`ci_testing` is strongly encouraged in order to avoid problems
+ that can be found when attempting to merge the patch.
4. If you modify existing code, make sure that your new code does not add to
the memory footprint of the code. Remember: Small is beautiful! When adding
- new features, these should compile conditionally only (using the
- configuration system resp. #ifdef), and the resulting code with the new
- feature disabled must not need more memory than the old code without your
- modification.
+ new features follow the guidelines laid out in :doc:`system_configuration`.
Patch Tracking
--------------
-Like some other project U-Boot uses `Patchwork <http://patchwork.ozlabs.org/>`_
+Like some other projects, U-Boot uses `Patchwork <http://patchwork.ozlabs.org/>`_
to track the state of patches. This is one of the reasons why it is mandatory
to submit all patches to the U-Boot mailing list - only then they will be
picked up by patchwork.
@@ -338,6 +334,13 @@ open U-Boot patches. By using the "Filters" link (Note: requires JavaScript)
you can also select other views, for example, to include old patches that have,
for example, already been applied or rejected.
+Note that Patchwork automatically tracks and collects a number of git tags from
+follow-up mails, so it is usually better to apply a patch through the Patchwork
+commandline interface than just manually applying it from a posting on the
+mailing list (in which case you have to do all the tracking and adding of git
+tags yourself). This also obviates the need of a developer to resubmit a patch
+only in order to collect these tags.
+
A Custodian has additional privileges and can:
* **Delegate** a patch
@@ -369,15 +372,13 @@ A Custodian has additional privileges and can:
Patchwork work-flow
^^^^^^^^^^^^^^^^^^^
-At the moment we are in the process of defining our work-flow with
-Patchwork, so I try to summarize what the states and state changes
-mean; most of this information is based on this `mail thread
-<http://old.nabble.com/patchwork-states-and-workflow-td19579954.html>`_.
+The following are a "rule of thumb" as to how the states are used in patchwork
+today. Not all states are used by all custodians.
* New: Patch has been submitted to the list, and none of the maintainers has
changed it's state since.
-* Under Review:
+* Under Review: A custodian is reviewing the patch currently.
* Accepted: When a patch has been applied to a custodian repository that gets
used for pulling from into upstream, they are put into "accepted" state.
@@ -387,30 +388,28 @@ mean; most of this information is based on this `mail thread
* RFC: The patch is not intended to be applied to any of the mainline
repositories, but merely for discussing or testing some idea or new feature.
-* Not Applicable: The patch does not apply cleanly against the current U-Boot
- repository, most probably because it was made against a much older version of
- U-Boot, or because the submitter's mailer mangled it (for example by
- converting TABs into SPACEs, or by breaking long lines).
+* Not Applicable: The patch either was not intended to be applied, as it was
+ a debugging or discussion aide that patchwork picked up, or was cross-posted
+ to our list but intended for another project entirely.
* Changes Requested: The patch looks mostly OK, but requires some rework before
it will be accepted for mainline.
-* Awaiting Upstream:
+* Awaiting Upstream: A custodian may have applied this to the ``next`` branch
+ and has not merged yet to master, or has queued the patch up to be submitted
+ to be merged, but has not yet.
* Superseeded: Patches are marked as 'superseeded' when the poster submits a
new version of these patches.
* Deferred: Deferred usually means the patch depends on something else that
isn't upstream, such as patches that only apply against some specific other
- repository.
+ repository. This is also used when a patch has been in patchwork for over a
+ year and it is unlikely to be applied as-is.
* Archived: Archiving puts the patch away somewhere where it doesn't appear in
the normal pages and needs extra effort to get to.
-We also can put patches in a "bundle". I don't know yet if that has any deeper
-sense but to mark them to be handled together, like a patch series that
-logically belongs together.
-
Apply patches
^^^^^^^^^^^^^
@@ -453,61 +452,3 @@ pwparser
^^^^^^^^
See http://www.mail-archive.com/patchwork@lists.ozlabs.org/msg00057.html
-
-Review Process, Git Tags
-------------------------
-
-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.
-
-* Signed-off-by: the *Signed-off-by:* is a line at the end of the commit
- message by which the signer certifies that he was involved in the development
- of the patch and that he accepts the `Developer Certificate of Origin
- <https://developercertificate.org/>`_. In U-Boot, we typically do not add a
- *Signed-off-by:* if we just pass on a patch without any changes.
-
-* 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 he 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:
-
-Note that Patchwork automatically tracks and collects such git tags
-from follow-up mails, so it is usually better to apply a patch through
-the Patchwork commandline interface than just manually applying it
-from a posting on the mailing list (in which case you have to do all
-the tracking and adding of git tags yourself).
--
2.25.1
More information about the U-Boot
mailing list