From 13ed966164f9b0488504f13b84496bb4c0c92a72 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Mon, 30 Sep 2019 12:18:57 +0200 Subject: user: Document patch review process --- images/user/patch-review.png | Bin 0 -> 66700 bytes images/user/patch-review.puml | 48 ++++++++++++++++++ user/support/contrib.rst | 111 ++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 156 insertions(+), 3 deletions(-) create mode 100644 images/user/patch-review.png create mode 100644 images/user/patch-review.puml diff --git a/images/user/patch-review.png b/images/user/patch-review.png new file mode 100644 index 0000000..ddfaf38 Binary files /dev/null and b/images/user/patch-review.png differ diff --git a/images/user/patch-review.puml b/images/user/patch-review.puml new file mode 100644 index 0000000..8134859 --- /dev/null +++ b/images/user/patch-review.puml @@ -0,0 +1,48 @@ +' SPDX-License-Identifier: CC-BY-SA-4.0 + +' Copyright (C) 2019 embedded brains GmbH + +@startuml + +start + +:Arrange your changes in\nan easy to review and\ncoherent patch series; + +:Apply the checklist for patches; + +:Invoke: ""git format-patch""; + +:Send the patch series to devel@rtems.org for review; + +:Set N to 1; + +while (Reviewers demand changes in the patch series?) is (Yes) + :Do the required changes and create a new patch series; + + :Update the commit messages accordingly; + + :Apply the checklist for patches; + + :Set N to N + 1; + + :Invoke: ""git format-patch -v $N""; + + :Document the changes from version N - 1 to N\nin the patch file after the "---" line; + + :Send the patch series to devel@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 + Push performed by an approved + RTEMS committer. + end note +else (No) + :Discard the patch series; +endif + +stop + +@enduml diff --git a/user/support/contrib.rst b/user/support/contrib.rst index 04c5dd8..c42d41b 100644 --- a/user/support/contrib.rst +++ b/user/support/contrib.rst @@ -12,10 +12,115 @@ Contributing ************ -Developers can find help and support on the :r:list:`devel`. +How to Contribute? +================== -Technical documents including design, :r:url:`gsoc`, :r:url:`socis` can be -found on the :r:url:`devel`. +You can contribute to the RTEMS Project in various ways, for example: + +* participation in mailing list discussions, helping other users + +* documentation updates, clarifications, consolidation, fixes + +* bug fixes, bug report consolidation + +* new BSPs + +* new device drivers + +* new CPU (processor architecture) ports + +* improvements in the existing code base (code size, code clarity, test + coverage, performance optimizations) + +* new features + +* RTEMS Tools improvements + +Most contributions will end up in patches of the RTEMS source code or +documentation sources. The patch integration into the RTEMS repositories is +done through a +:ref:`patch review process ` +on the :r:list:`devel`. + +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 `_. +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 `_. + +.. _ChecklistForPatches: + +Checklist for Patches +===================== + +Check the following items before you send a patch to the :r:list:`devel`: + +* The author name of the patch is your full name. + +* The author email of the patch is your valid email address. + +* The licence conditions of the contributed content allow an integration into + the RTEMS code base. + +* If you are the copyright holder of the entire patch content, then please + contribute it under the + `BSD-2-Clause `_ + license. For documentation use + `CC 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. + +* If the patch corresponds to a ticket, it should have "Close #X." or + "Update #X." as the last line in the commit message to update status once it + is committed to the repository. + +* The patch builds. All RTEMS tests link with this patch. + +* The patch does not introduce new compiler warnings. + +* The patch does not introduce new test failures in existing tests. + +Patch Review Process +==================== + +Patches sent to the :r:list:`devel` undergo a +:ref:`patch review process `. +Once a patch series is accepted for integration into the RTEMS code base it is +committed by an +`RTEMS maintainer `_. The +maintainers are usually quite busy with all sorts of stuff. If you do not get a +response to a patch series submission to the mailing list after five work days, +please send a reminder. It helps if you follow the :ref:`ChecklistForPatches`. +An easy to review patch series which meets the quality standards of the RTEMS +Project will be more likely get integrated quickly. + +.. _PatchReviewProcess: + +.. figure:: ../../images/user/patch-review.* + :width: 70% + :alt: RTEMS Patch Review Process + :figclass: align-center + + RTEMS Patch Review Process. Why Contribute? =============== -- cgit v1.2.3