Add pull request guideline

aschaal · rolandreichweinbmw · commit 81a3f07a0485 · 2025-11-25T10:36:21.000+01:00
Change-Id: Ib06883182ee9d7e4a15f317f6f3418bca6271f82
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -2,13 +2,13 @@
 
 Before considering contributing you should be familiar with Eclipse OpenBSW project.
 
- * You should have [set up a working environment](https://eclipse-openbsw.github.io/openbsw/sphinx_docs/doc/dev/learning/setup/index.html)
+ * You should have [Set Up a Working Environment](https://eclipse-openbsw.github.io/openbsw/sphinx_docs/doc/dev/learning/setup/index.html)
    in which you can build and test.
- * You should be familiar with...
-    + [Coding Guidelines](https://eclipse-openbsw.github.io/openbsw/sphinx_docs/doc/dev/codingGuidelines/index.html)
-    + [Code of Conduct](CODE_OF_CONDUCT.md)
+ * You should be familiar with
+   the [Guidelines](https://eclipse-openbsw.github.io/openbsw/sphinx_docs/doc/index.html) and
+   the [Code of Conduct](CODE_OF_CONDUCT.md).
  * Contributions should pass all automated builds and tests,
-including [building the documentation](doc/README.md).
+including [Building the Documentation](doc/README.md).
 
 ## How Can I Contribute?
 
@@ -35,7 +35,7 @@ Simply choose the issue you would want to work on, and tell everyone
 that you are willing to do so and how you would approach it. The team will be
 happy to guide you and give feedback.
 
-To contribute your work you need to...
+To contribute your work you need to:
 
 1. Fork the [Eclipse OpenBSW](https://github.com/eclipse-openbsw/openbsw) project
 2. Create your Branch (`git checkout -b newBranchName`)
@@ -50,11 +50,6 @@ electronically sign the Eclipse Contributor Agreement (ECA).
 
 * https://www.eclipse.org/legal/eca/
 
-Commits that are provided by non-committers must have a Signed-off-by field in
-the footer indicating that the author is aware of the terms by which the
-contribution has been provided to the project. The non-committer must
-additionally have an Eclipse Foundation account and must have a signed Eclipse
-Contributor Agreement (ECA) on file.
 
 For more information, please see the Eclipse Committer Handbook:
 https://www.eclipse.org/projects/handbook/#resources-commit
@@ -65,60 +60,3 @@ To complete and submit a ECA, log into the
 Click on "Eclipse Contributor Agreement" and complete the form.
 Be sure to use the same email address when you register for the account
 that you intend to use when you commit to Git.
-
-## Sign your work
-
-The sign-off is a simple line at the end of the explanation for the patch. Your
-signature certifies that you wrote the patch or otherwise have the right to
-pass it on as an open-source patch. The rules are pretty simple: if you can
-certify the below
-(from [https://www.eclipse.org/legal/dco/](https://www.eclipse.org/legal/dco/)):
-
-```
-Developer Certificate of Origin
-Version 1.1
-
-Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
-1 Letterman Drive
-Suite D4700
-San Francisco, CA, 94129
-
-Everyone is permitted to copy and distribute verbatim copies of this
-license document, but changing it is not allowed.
-
-
-Developer's Certificate of Origin 1.1
-
-By making a contribution to this project, I certify that:
-
-(a) The contribution was created in whole or in part by me and I
-    have the right to submit it under the open source license
-    indicated in the file; or
-
-(b) The contribution is based upon previous work that, to the best
-    of my knowledge, is covered under an appropriate open source
-    license and I have the right under that license to submit that
-    work with modifications, whether created in whole or in part
-    by me, under the same open source license (unless I am
-    permitted to submit under a different license), as indicated
-    in the file; or
-
-(c) The contribution was provided directly to me by some other
-    person who certified (a), (b) or (c) and I have not modified
-    it.
-
-(d) I understand and agree that this project and the contribution
-    are public and that a record of the contribution (including all
-    personal information I submit with it, including my sign-off) is
-    maintained indefinitely and may be redistributed consistent with
-    this project or the open source license(s) involved.
-```
-
-Then you just add a line to every git commit message:
-
-    Signed-off-by: Joe Smith <joe.smith@email.com>
-
-Use your real name (sorry, no pseudonyms or anonymous contributions.)
-
-If you set your `user.name` and `user.email` git configs, you can sign your
-commit automatically with `git commit -s`.
diff --git a/doc/README.md b/doc/README.md
@@ -1,45 +1,49 @@
-# Building the project documentation
+# Building the Project Documentation
 
-## Building documentation with [`Sphinx`](https://www.sphinx-doc.org/)
+## Building Developer Documentation With [`Sphinx`](https://www.sphinx-doc.org/)
 
-[`Download Zipped Documentation`](https://github.com/esrlabs/open-bsw/releases/download/preview/open-bsw-doc.zip)
+Sphinx is a documentation generator originally created for the Python language, but now used widely
+for many kinds of projects including C++.
 
-Documentation in RST format throughout the code can be exported to HTML as described below.
+Sphinx uses
+[`reStructuredText`](https://docutils.sourceforge.io/rst.html) as its markup language.
+If you are not familiar with reStructuredText, you may read the
+[`reStructuredText Primer`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)
+on the Sphinx webpage first.
 
 Prerequisites:
-- Python 3.10.x
-- [`plantuml`](https://plantuml.com/starting)
-
-First install the required Python modules:
-```bash
-pip install -r requirements.txt
-```
-and then build the documentation calling:
+- Install Python 3.10 or higher
+- Install [`plantuml`](https://plantuml.com/starting)
+- Install the required Python modules:
+  ```bash
+  pip install -r doc/dev/requirements.txt
+  ```
+
+To build the documentation, go to `doc/dev` and call:
 ```bash
 make html
 ```
 
-## Building documentation with [`Doxygen`](https://www.doxygen.nl/)
+The entry point HTML page is found at `doc/dev/build/html/doc/dev/index.html`.
 
-Using the settings file ``doc/api/Doxyfile``,
-`Doxygen` will generate documentation
-from formatted comments in C/C++ code in the subdirectories...
+## Building API Documentation with [`Doxygen`](https://www.doxygen.nl/)
 
-* ``libs/bsp``
-* ``libs/bsw``
-
-by running the following in the ``doc/api`` directory...
+ Using the settings file `doc/api/Doxyfile`, Doxygen generates the documentation from formatted
+comments in the C/C++ code across all relevant subfolders; see
+[Doxygen Main Page](DoxygenMainPage.md) for details.
 
+To build the documentation, go to `doc/api` and call:
 ```bash
 doxygen Doxyfile
 ```
 
-The entry point html file is found at `doc/api/doxygenOut/html/index.html`
+The entry point HTML page is found at `doc/api/doxygenOut/html/index.html`.
 
-XML output is also generated in  `doc/api/doxygenOut/xml/` from which coverage information can be extracted using [`coverxygen`](https://github.com/psycofdj/coverxygen). For example...
+XML output is also generated in  `doc/api/doxygenOut/xml/` from which coverage information can
+be extracted using [`coverxygen`](https://github.com/psycofdj/coverxygen). For example:
 
 ```bash
-$ python3 -m coverxygen --format summary --xml-dir doxygenOut/xml/ --src-dir .. --output -
+$ python3 -m coverxygen --format summary --xml-dir doxygenOut/xml/ --src-dir ../.. --output -
 Classes    :  50.2% (231/460)
 Defines    :   2.4% (4/169)
 Enum Values:  35.9% (185/515)
@@ -55,5 +59,4 @@ Unions     : 100.0% (1/1)
 Variables  :   7.7% (110/1435)
 -----------------------------------
 Total      :  30.9% (2743/8886)
-
-```
+```
diff --git a/doc/api/DoxygenMainPage.md b/doc/api/DoxygenMainPage.md
@@ -1,4 +1,3 @@
-
 # Eclipse OpenBSW
 
 This documentation was generated by Doxygen from the code in the subdirectories:
diff --git a/doc/dev/guidelines/module.rst b/doc/dev/guidelines/module.rst
@@ -64,6 +64,8 @@ tools
 
 Optional folder for tools or scripts related to this module.
 
+.. _module_spec:
+
 module.spec
 -----------
 
@@ -98,6 +100,9 @@ Every module requires a ``module.spec`` file which includes the basic settings o
                                 # Additional security tests are
                                 # executed on this module.
 
+    unit_test: false            # Module must have a unit test    [true, false]                  true
+
+
 .. note::
     - Only properties differing from their respective default values should be stated in the
       ``module.spec`` file.
diff --git a/doc/dev/guidelines/pull_request.rst b/doc/dev/guidelines/pull_request.rst
@@ -0,0 +1,69 @@
+Pull Request
+============
+
+Contributing
+------------
+
+To contribute to this project, follow the process described in
+`CONTRIBUTING.md <https://github.com/eclipse-openbsw/openbsw/blob/main/CONTRIBUTING.md>`_.
+Every author must electronically sign the Eclipse Contributor Agreement.
+
+Description
+-----------
+
+A pull request description serves a similar purpose as a :ref:`commit_message`. Therefore,
+**all rules for commit messages also apply to pull requests**, with the following exceptions:
+
+- The **comment fields** are not limited to 72 characters per line.
+- All **markup syntaxes** supported on GitHub are allowed.
+
+| If a PR consists of just **one commit**, the pull request description can be **identical** to the
+  commit message.
+| If a PR consists of **several commits**, the pull request description should **summarize** the
+  commits.
+
+Approval Process
+----------------
+
+As per the `Eclipse Foundation Specification Process <https://www.eclipse.org/projects/efsp/>`_,
+every committer has the "rights to make decisions regarding a Project", including the authority
+to approve commits.
+
+In OpenBSW, we follow that process with the following addition:
+
+If the pull request is **small enough** and the committer has the **complete overview** of the pull
+request and its **consequences**, the **committer can approve and merge** the pull request without
+consulting other committers. Examples:
+
+- fixing typos or software bugs
+- improving documentation
+- making CI more robust
+- enhancing a feature
+
+If the pull request changes **processes, strategies, fundamentals or important APIs**, the
+pull request must be **discussed** with other committers. Examples:
+
+- changing the workspace structure
+- adding a completely new feature
+- removing support for older compilers
+- changing guidelines
+
+There is always a grey zone. In case of doubt, the committer must consult other committers.
+
+Checklist
+---------
+
+The committer must take the following points into account before approving the pull request:
+
+- Do the **commit messages** and pull request **description follow the guidelines**?
+- Is the code **useful** and should it be part of OpenBSW?
+- Is **documentation** provided?
+- Are **tests** changed or added?
+- Is the contribution, including code, tests, and documentation, **compliant with the guidelines**?
+
+Some checks might not be applicable, e.g., if unit tests are explicitly excluded in
+:ref:`module_spec`.
+
+In case of findings, the pull request must not be approved or merged.
+Alternatively, e.g., if it is planned to post-deliver the documentation, a GitHub issue must be
+created and linked in the pull request.
diff --git a/doc/dev/index.rst b/doc/dev/index.rst
@@ -141,6 +141,7 @@ Eclipse OpenBSW is a trademark of the Eclipse Foundation.
     guidelines/diagrams
     guidelines/3rdparty
     guidelines/commit_message
+    guidelines/pull_request
 
 .. toctree::
     :maxdepth: 2

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,3 @@`
`1`		`-`
`2`	`1`	`# Eclipse OpenBSW`
`3`	`2`
`4`	`3`	`This documentation was generated by Doxygen from the code in the subdirectories:`