[4/7] doc: Migrate Process wiki page to Sphinx

Move the current Process wiki page to doc/develop/process.rst.  The
changes here are for formatting or slight rewording so that it reads
well when linking to other Sphinx documents.

Cc: Heinrich Schuchardt <xypron.glpk@gmx.de>
Signed-off-by: Tom Rini <trini@konsulko.com>
---
Changes in v2:
- Assorted wiki -> Sphinx style corrections and a few typo fixes, per
  Heinrich
---
 doc/develop/index.rst   |   1 +
 doc/develop/process.rst | 200 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 201 insertions(+)
 create mode 100644 doc/develop/process.rst

On 7/11/22 19:14, Tom Rini wrote:
> Move the current Process wiki page to doc/develop/process.rst.  The
> changes here are for formatting or slight rewording so that it reads
> well when linking to other Sphinx documents.
>
> Cc: Heinrich Schuchardt <xypron.glpk@gmx.de>
> Signed-off-by: Tom Rini <trini@konsulko.com>
> ---
> Changes in v2:
> - Assorted wiki -> Sphinx style corrections and a few typo fixes, per
>    Heinrich
> ---
>   doc/develop/index.rst   |   1 +
>   doc/develop/process.rst | 200 ++++++++++++++++++++++++++++++++++++++++
>   2 files changed, 201 insertions(+)
>   create mode 100644 doc/develop/process.rst
>
> diff --git a/doc/develop/index.rst b/doc/develop/index.rst
> index c0f4f0ba413a..eab00a55382a 100644
> --- a/doc/develop/index.rst
> +++ b/doc/develop/index.rst
> @@ -11,6 +11,7 @@ General
>
>      codingstyle
>      designprinciples
> +   process
>
>   Implementation
>   --------------
> diff --git a/doc/develop/process.rst b/doc/develop/process.rst
> new file mode 100644
> index 000000000000..534da4a2a704
> --- /dev/null
> +++ b/doc/develop/process.rst
> @@ -0,0 +1,200 @@
> +.. SPDX-License-Identifier: GPL-2.0+:
> +
> +U-Boot Development Process
> +==========================
> +
> +Management Summary
> +------------------
> +
> +* Development happens in Release Cycles of 3 months.
> +
> +* The first 2 weeks are called Merge Window, which is followed by a
> +  Stabilization Period.
> +
> +* Patches with new code get only accepted while the Merge Window is open.
> +
> +* A patch that is generally in good shape and that was submitted while the
> +  Merge Window was open is eligible to go into the upcoming release, even if
> +  changes and resubmits are needed.
> +
> +* During the Stabilization Period, only patches that contain bug fixes get
> +  applied.
> +
> +Phases of the Development Process
> +---------------------------------
> +
> +U-Boot development takes place in `Release Cycles
> +<https://www.denx.de/wiki/U-Boot/ReleaseCycle>`_.  A Release Cycle lasts
> +normally for three months.
> +
> +The first two weeks of each Release Cycle are called *Merge Window*.
> +
> +It is followed by a *Stabilization Period*.
> +
> +The end of a Release Cycle is marked by the release of a new U-Boot version.
> +
> +Merge Window
> +------------
> +
> +The Merge Window is the period when new patches get submitted
> +(and hopefully accepted) for inclusion into U-Boot mainline.
> +
> +This is the only time when new code (like support for new processors or new
> +boards, or other new features or reorganization of code) is accepted.
> +
> +Twilight Time
> +-------------
> +
> +Usually patches do not get accepted as they are - the peer review that takes
> +place will usually require changes and resubmits of the patches before they
> +are considered to be ripe for inclusion into mainline.
> +
> +Also, the review often happens not immediately after a patch was submitted,
> +but only when somebody (usually the responsible custodian) finds time to do
> +this.
> +
> +In the result, the final version of such patches gets submitted after the
> +merge window has been closed.
> +
> +It is current practice in U-Boot that such patches are eligible to go into the
> +upcoming release.
> +
> +In the result, the release of the ``"-rc1"`` version does not immediately follow
> +the closing of the Merge Window.
> +
> +Stabilization Period
> +--------------------
> +
> +During the Stabilization Period only patches containing bug fixes get
> +applied.
> +
> +Corner Cases
> +------------
> +
> +Sometimes it is not clear if a patch contains a bug fix or not.
> +For example, changes that remove dead code, unused macros etc. or
> +that contain Coding Style fixes are not strict bug fixes.
> +
> +In such situations it is up to the responsible custodian to decide if he
> +applies such patches even when the Merge Window is closed.
> +
> +Exception: at the end of the Stabilization Period only strict bug
> +fixes my be applied.
> +
> +Sometimes patches miss the the Merge Window slightly - say by few
> +hours or even a day. Patch acceptance is not as critical as a
> +financial transaction, or such. So if there is such a slight delay,
> +the custodian is free to turn a blind eye and accept it anyway. The
> +idea of the development process is to make it foreseeable,
> +but not to slow down development.
> +
> +It makes more sense if an engineer spends another day on testing and
> +cleanup and submits the patch a couple of hours late, instead of
> +submitting a green patch which will waste efforts from several people
> +during several rounds of review and reposts.
> +
> +Differences to the Linux Development Process
> +--------------------------------------------
> +
> +* In Linux, top-level maintainers will collect patches in their trees and send
> +  pull requests to Linus as soon as the merge window opens.
> +  So far, most U-Boot custodians do not work like that; they send pull requests
> +  only at (or even after) the end of the merge window.
> +
> +* In Linux, the closing of the merge window is marked by the release of the
> +  next ``"-rc1"``
> +  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
> +----------
> +
> +The Custodians take responsibility for some area of the U-Boot code.  The
> +in-tree ``MAINTAINERS`` files list who is reponsible for which areas.
> +
> +It is their responsibility to pick up patches from the mailing list
> +that fall into their responsibility, and to process these.
> +
> +A very important responsibility of each custodian is to provide
> +feedback to the submitter of a patch about what is going on: if the
> +patch was accepted, or if it was rejected (which exact list of
> +reasons), if it needs to be reworked (with respective review
> +comments). Even a "I have no time now, will look into it later"
> +message is better than nothing. Also, if there are remarks to a
> +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
> +------------------------
> +
> +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.
> +
> +#. Everybody who can is invited to review and test the changes.  Reviews should
> +   reply on the mailing list with ``Acked-by`` lines.
> +
> +#. The responsible custodian
> +
> +   #. inspects this patch, especially for:

This should not be a bullet point.

> +
> +   #. :doc:`codingstyle`
> +
> +   #. Basic logic:
> +
> +      * The patch fixes a real problem.
> +
> +      * The patch does not introduce new problems, especially it does not break
> +        other boards or architectures
> +
> +   #. U-Boot Philosophy
> +
> +   #. Applies cleanly to the source tree
> +
> +   #. passes a ``MAKEALL`` compile test without creating new warnings
> +
> +#. 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 himself 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.

This paragraph is unclear. How about:

Patches should be based on the git HEAD. If merge conflicts arise, the
custodian decides to either rebase the patch himself or to request the
submitter for a rebased patch.

> +
> +  #. Commits should show original author in the ``author`` field and include all
> +      sign off/ack lines.

Sign-off, Acked-by, Reviewed-by lines.

Best regards

Heinrich

> +
> +#. The custodian decides to accept or to reject the patch.
> +
> +#. If accepted, the custodian adds the patch to his public git repository and
> +   notifies the mailing list. This note should include:
> +
> +   * a short description of the changes
> +
> +   * the list of the affected boards / architectures etc.
> +
> +   * suggested tests
> +
> +   Although the custodian is supposed to perform his own tests
> +   it is a well-known and accepted fact that he 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.
> +
> +#. Once tests are passed, some agreed time limit expires, the custodian
> +   requests that the changes in his public git repository be merged into the
> +   main tree. If necessary, the custodian may have to adapt his changes to
> +   allow for a clean merge.
> +   Todo: define a reasonable time limit. 3 weeks?

On Wed, Jul 13, 2022 at 07:36:02PM +0200, Heinrich Schuchardt wrote:
> On 7/11/22 19:14, Tom Rini wrote:
[snip]
> > +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.
> > +
> > +#. Everybody who can is invited to review and test the changes.  Reviews should
> > +   reply on the mailing list with ``Acked-by`` lines.
> > +
> > +#. The responsible custodian
> > +
> > +   #. inspects this patch, especially for:
> 
> This should not be a bullet point.
> 
> > +
> > +   #. :doc:`codingstyle`
> > +
> > +   #. Basic logic:
> > +
> > +      * The patch fixes a real problem.
> > +
> > +      * The patch does not introduce new problems, especially it does not break
> > +        other boards or architectures
> > +
> > +   #. U-Boot Philosophy
> > +
> > +   #. Applies cleanly to the source tree
> > +
> > +   #. passes a ``MAKEALL`` compile test without creating new warnings
> > +
> > +#. 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 himself 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.
> 
> This paragraph is unclear. How about:
> 
> Patches should be based on the git HEAD. If merge conflicts arise, the
> custodian decides to either rebase the patch himself or to request the
> submitter for a rebased patch.
> 
> > +
> > +  #. Commits should show original author in the ``author`` field and include all
> > +      sign off/ack lines.
> 
> Sign-off, Acked-by, Reviewed-by lines.

Please comment on the later patch where I re-write this section a good
deal.  To repeat, I do not want to make significant changes to these
documents in the same commit that imports them from the wiki.