[PATCH 7/7] process.rst: Modernize the "Workflow of a Custodian" section
xypron.glpk at gmx.de
Wed Jul 13 19:46:28 CEST 2022
On 7/11/22 19:14, Tom Rini wrote:
> 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 at denx.de>
> Cc: Martin Bonner <martingreybeard at gmail.com>
> Cc: Heinrich Schuchardt <xypron.glpk at gmx.de>
> Signed-off-by: Tom Rini <trini at konsulko.com>
> Changes in v2:
> - New patch
> doc/develop/process.rst | 88 ++++++++++++++++++++---------------------
> 1 file changed, 42 insertions(+), 46 deletions(-)
> diff --git a/doc/develop/process.rst b/doc/develop/process.rst
> index d0c46b58f3e9..56c9d274be71 100644
> --- 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
> + have been complete prior to submission, but not required.
A run is singular.
More information about the U-Boot