process.rst: Modernize the "Workflow of a Custodian" section

The "Workflow of a Custodian" section on the wiki had not been changed
in quite some time to reflect how the process has been functioning for
some time.  First, update some links to point to modern and current
sources of information.

Second, and more overarching, reword much of the section.  This expands
on the expectations of both custodians and developers when it comes to
rebasing patches.  Rework the final points to be clearer that Custodians
are expected to do their best to test the changes and ask for help when
needed, as well as that pull requests are expected in a timely manner.

Cc: Claudius Heine <ch@denx.de>
Cc: Martin Bonner <martingreybeard@gmail.com>
Cc: Heinrich Schuchardt <xypron.glpk@gmx.de>
Signed-off-by: Tom Rini <trini@konsulko.com>

diff --git a/doc/develop/process.rst b/doc/develop/process.rst
index d0c46b58f3e94f68be718f7423acdc4e0adc45c1..4ba4bb2d657b6918515354bf1f7eb7876938b523 100644 (file)
--- a/doc/develop/process.rst
+++ b/doc/develop/process.rst
@@ -132,16 +132,20 @@ Work flow of a Custodian
 The normal flow of work in the U-Boot development process will look
 like this:
 
-#. A developer submits a patch via e-mail to the u-boot-users mailing list.
-   U-Boot has adopted the `Linux kernel signoff policy <https://groups.google.com/g/fa.linux.kernel/c/TLJIJVA-I6o?pli=1>`_, so the submitter must
-   include a ``Signed-off-by:`` line.
+#. 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.
 
-#. Everybody who can is invited to review and test the changes.  Reviews should
-   reply on the mailing list with ``Acked-by`` lines.
+#. 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.
 
-#. The responsible custodian
-
-   #. inspects this patch, especially for:
+#. The responsible custodian inspects this patch, especially for:
 
    #. :doc:`codingstyle`
 
@@ -152,50 +156,42 @@ like this:
       * The patch does not introduce new problems, especially it does not break
         other boards or architectures
 
-   #. U-Boot Philosophy
+   #. U-Boot Philosophy, as documented in :doc:`designprinciples`.
 
-   #. Applies cleanly to the source tree
+   #. Applies cleanly to the source tree.  The custodian is expected to put in
+      a "best effort" if a patch does not apply cleanly, but can be made to apply
+      still.  It is up to the custodian to decide how recent of a commit the
+      patch must be against.  It is acceptable to request patches against the
+      last officially released version of U-Boot or newer.  Of course a
+      custodian can also accept patches against older code.  It can be
+      difficult to find the correct balance between putting too much work on
+      the custodian or too much work on an individual submitting a patch when
+      something does not apply cleanly.
 
    #. Passes :doc:`ci_testing` as this checks for new warnings and other issues.
 
-#. Notes:
-
-  #. In some cases more than one custodian may be affected or feel responsible.
-     To avoid duplicated efforts, the custodian who starts processing the
-     patch should send a short ACK to the mailing list.
-
-  #. We should create some tool to automatically do this.
-
-  #. This is well documented in :doc:`designprinciples`.
-
-  #. The custodian decides themselves how recent the code must be.  It is
-     acceptable to request patches against the last officially released
-     version of U-Boot or newer.  Of course a custodian can also accept
-     patches against older code.
-
-  #. Commits should show original author in the ``author`` field and include all
-      sign off/ack lines.
-
-#. The custodian decides to accept or to reject the patch.
-
-#. If accepted, the custodian adds the patch to their public git repository and
-   notifies the mailing list. This note should include:
+#. Note that in some cases more than one custodian may feel responsible for a
+   particular change.  To avoid duplicated efforts, the custodian who starts
+   processing the patch should follow up to the email saying they intend to
+   pick it up.
 
-   * a short description of the changes
+#. Commits must show original author in the ``author`` field and include all of
+   the ``Signed-off-by``, ``Reviewed-by``, etc, tags that have been submitted.
 
-   * the list of the affected boards / architectures etc.
+#. The final decision to accept or reject a patch comes down to the custodian
+   in question.
 
-   * suggested tests
+#. If accepted, the custodian adds the patch to their public git repository.
+   Ideally, they will also follow up on the mailing list with some notification
+   that it has been applied.  This is not always easy given different custodian
+   workflows and environments however.
 
-   Although the custodian is supposed to perform their own tests
-   it is a well-known and accepted fact that they needs help from
-   other developers who - for example - have access to the required
-   hardware or tool chains.
-   The custodian request help for tests and feedback from
-   specific maintainers and U-Boot users.
+#. Although a custodian is supposed to perform their own tests it is a
+   well-known and accepted fact that they needs help from other developers who
+   - for example - have access to the required hardware or other relevant
+   environments.  Custodians are expected to ask for assistance with testing
+   when required.
 
-#. Once tests are passed, some agreed time limit expires, the custodian
-   requests that the changes in their public git repository be merged into the
-   main tree. If necessary, the custodian may have to adapt their changes to
-   allow for a clean merge.
-   Todo: define a reasonable time limit. 3 weeks?
+#. Custodians are expected to submit a timely pull request of their git
+   repository to the main repository.  It is strongly encouraged that a CI run
+   has been completed prior to submission, but not required.