[PATCH] user: Document patch review process

[Chris Johns]

On 30/9/19 10:45 pm, Sebastian Huber wrote:
> ---
>  images/user/patch-review.png  | Bin 0 -> 57130 bytes
>  images/user/patch-review.puml |  44 +++++++++++++++++++++++++++
>  user/support/contrib.rst      |  67 +++++++++++++++++++++++++++++++++---------
>  3 files changed, 97 insertions(+), 14 deletions(-)
>  create mode 100644 images/user/patch-review.png
>  create mode 100644 images/user/patch-review.puml
> 

If you want to review the figure it is ...

http://www.plantuml.com/plantuml/png/dP0_ZzDC4CRx_HGZwoqIlSf9K8Q28451ST7f3WgaD7lsutZ1EsjcnuxoxLcFWt9790gAbNR-_6QUUNPPlUWOU-VivzpsWuZd8-YSHg6wc_-P0X_OCy7dCsaYmHHm8i_DWUlKGS1AWzUwemm9oE_AeCyyfH_OKbKTWrAR97hTM5DLpVKdS4FQuHKuJsymeT-98kQx9CSPlMnSCANztFQsHASkzA3LerKXkR2ng7gX-sR3-pM5JAjlo6j7jFsOh4FmSmo2AsbJ15v1dXYdFyyhwDUXcSjrYZ4eHUJiZQph94tWOt-slhyOGPk9_jkR7IQb7YDOJT1l7QsaI1CaXyJBtNlwdzuS-DLfxMo3RnLYoMgpsLJK1uPDDi-khEN-pVx2N2pVfxLpeQNLmqlyvEr-38g6diyN3b9SdtVnrVU7CNStwm-iQKbA-evQIJ2a73J9OYKd1KauTbe2elinAps3ciIOjtcszEENJ_TF57rWBGzoLxBWncY7FY_gpV6GQo-tDjYXeNKkQngSsvLeZFql

> diff --git a/images/user/patch-review.puml b/images/user/patch-review.puml
> new file mode 100644
> index 0000000..4bfbe9f
> --- /dev/null
> +++ b/images/user/patch-review.puml
> @@ -0,0 +1,44 @@
> +' SPDX-License-Identifier: CC-BY-SA-4.0
> +
> +' Copyright (C) 2019 embedded brains GmbH
> +
> + at startuml
> +
> +start
> +
> +:Arrange your changes in\nan easy to review and\ncoherent patch series;
> +
> +:Invoke: ""git format-patch"";
> +
> +:Send the patch series to devel at rtems.org for review;
> +
> +:Set N to 2;
> +
> +while (Reviewers demand changes in the patch series?) is (Yes)
> +  :Do the required changes and create a new patch series;
> +
> +  :Update commit messages accordingly;
> +
> +  :Invoke: ""git format-patch -v $N"";
> +
> +  :Document the changes from version N to N + 1\nin the patch file after the "---" line;
> +
> +  :Set N to N + 1;
> +
> +  :Send the patch series to devel at rtems.org for review;
> +endwhile (No)
> +
> +if (Patch series was accepted by reviewers?) then (Yes)
> +  :Push the patch series\nto the project repository;
> +
> +  note right
> +    Must be done by an
> +    RTEMS maintainer.
> +  end note
> +else (No)
> +  :Discard the patch series;
> +endif
> +
> +stop
> +
> + at enduml
> diff --git a/user/support/contrib.rst b/user/support/contrib.rst
> index 79d70a0..a57900d 100644
> --- a/user/support/contrib.rst
> +++ b/user/support/contrib.rst
> @@ -12,11 +12,6 @@
>  Contributing
>  ************
>  
> -Developers can find help and support on the :r:list:`devel`.
> -
> -Technical documents including design, :r:url:`gsoc`, :r:url:`socis` can be
> -found on the :r:url:`devel`.
> -
>  How to Contribute?
>  ==================
>  
> @@ -42,8 +37,10 @@ You can contribute to the RTEMS Project in various ways, for example:
>  * RTEMS Tools improvements
>  
>  Most contributions will end up in patches of the RTEMS source code or
> -documentation sources.  The patch integration in the RTEMS repositories is done
> -through a patch review process on the :r:list:`devel`.
> +documentation sources.  The patch integration into the RTEMS repositories is
> +done through a
> +:ref:`patch review process <PatchReviewProcess>`
> +on the :r:list:`devel`.
>  
>  Preparing and Sending Patches
>  =============================
> @@ -51,15 +48,17 @@ Preparing and Sending Patches
>  The RTEMS Project uses Git for version control.  Git has a special command to
>  prepare patches intended for mailing lists:
>  `git format-patch <https://git-scm.com/docs/git-format-patch>`_.
> -Create logically connected patches as a patch set ideally accompanied by a cover
> -letter (``--cover-letter`` option).  You can send patches via email through a
> -Git command:
> +Create logically connected patches as a patch series ideally accompanied by a
> +cover letter (``--cover-letter`` option).  You can send patches via email
> +through a Git command:
>  `git send-email <https://git-scm.com/docs/git-send-email>`_.
>  
> -Checklist for a Patch
> +.. _ChecklistForPatches:
> +
> +Checklist for Patches
>  =====================
>  
> -Check the following items before you send a patch to :r:list:`devel`:
> +Check the following items before you send a patch to the :r:list:`devel`:
>  
>  * The author name of the patch is your full name.
>  
> @@ -72,12 +71,52 @@ Check the following items before you send a patch to :r:list:`devel`:
>    contribute it under the
>    `BSD-2-Clause <https://git.rtems.org/rtems/tree/LICENSE.BSD-2-Clause>`_
>    license.  For documentation use
> -  `CC BY-SA 4.0 <https://creativecommons.org/licenses/by-sa/4.0/`_.
> +  `CC BY-SA 4.0 <https://creativecommons.org/licenses/by-sa/4.0/>`_.
> +
> +* Make sure you have a pregnant subject which does not exceed 50 characters in
> +  one line.  Use a "topic: The pregnant subject" style.  A topic could be the
> +  main component of patch.  Just have a look at existing commit messages.
> +
> +* The patch has a good commit message.  It should describe the reason for the
> +  change.  It should list alternative approaches and why they were not chosen.
> +
> +* The code changes honour the coding style.  At least do your changes in the
> +  style of the surrounding code.
> +
> +* The patch contains no spelling mistakes and grammar errors.
> +
> +* The patch is easy to review.  It changes one thing only and contains no
> +  unrelated changes.  Format changes should be separated from functional
> +  changes.
> +
> +* The patch builds.  All RTEMS tests link with this patch.
> +
> +* The patch does not introduce new compiler warnings.

This step is not in the figure.

Built against which BSPs?

> +* The patch does not introduce new test failures in existing tests.

This step is not in the figure.

Again which BSPs? This assumes expected fails are valid for the bsps being tested.

What about tickets and the "Closes ...", "Updates ..." etc tags?

Chris