Skip to content

Commit 96dbb4b

Browse files
jsquyresjsquyres
authored
Merge pull request #10597 from jsquyres/pr/contributing-to-open-mpi
Consolidate "contributing to Open MPI" docs
2 parents 7900166 + bf52156 commit 96dbb4b

File tree

3 files changed

+143
-136
lines changed

3 files changed

+143
-136
lines changed

‎.github/CONTRIBUTING.md

Lines changed: 9 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -5,85 +5,14 @@ Open MPI!
55

66
![You're awesome!](https://www.open-mpi.org/images/youre-awesome.jpg)
77

8-
General information about contributing to the Open MPI project can be found at the [Contributing to Open MPI webpage](https://www.open-mpi.org/community/contribute/).
9-
The instructions below are specifically for opening issues and pull requests against Open MPI.
8+
General information about contributing to the Open MPI project can be
9+
found at the [Contributing to Open MPI
10+
webpage](https://docs.open-mpi.org/en/main/contributing.html).
1011

11-
## Content
12+
In short: Open MPI is hosted on GitHub, and we gladly accept pull
13+
requests. The instructions below are specifically for opening issues
14+
and pull requests against Open MPI.
1215

13-
We love getting contributions from anyone. But keep in mind that Open
14-
MPI is used in production environments all around the world.
15-
16-
If you're contributing a small bug fix, awesome!
17-
18-
If you're contributing a large new piece of functionality, that will
19-
be best viewed if you — or someone, anyone — is also stepping up to
20-
help maintain that functionality over time. We love new ideas and new
21-
features, but we do need to be realistic in what we can reliably test
22-
and deliver to our users.
23-
24-
## Contributor's Declaration
25-
26-
In order to ensure that we can keep distributing Open MPI under our
27-
[open source license](/LICENSE), we need to ensure that all
28-
contributions are compatible with that license.
29-
30-
To that end, we require that all Git commits contributed to Open MPI
31-
have a "Signed-off-by" token indicating that the commit author agrees
32-
with [Open MPI's Contributor's
33-
Declaration](https://github.com/open-mpi/ompi/wiki/Administrative-rules#contributors-declaration).
34-
35-
If you have not already done so, please ensure that:
36-
37-
1. Every commit contains exactly the "Signed-off-by" token. You can
38-
add this token via `git commit -s`.
39-
1. The email address after "Signed-off-by" must match the Git commit
40-
email address.
41-
42-
## **Did you find a bug?**
43-
44-
* **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/open-mpi/ompi/issues).
45-
46-
* If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/open-mpi/ompi/issues/new).
47-
48-
* For more detailed information on submitting a bug report and creating an issue, visit our [Bug Tracking webpage](https://www.open-mpi.org/community/help/bugs.php).
49-
50-
## **Did you write a patch that fixes a bug?**
51-
52-
* Open a new GitHub pull request with the patch.
53-
54-
* Ensure the PR description clearly describes the problem and solution. If there is an existing GitHub issue open describing this bug, please include it in the description so we can close it.
55-
56-
* Before submitting, please read the [Contributing to the Open MPI Project FAQ](https://www.open-mpi.org/faq/?category=contributing) web page, and the [SubmittingPullRequests](https://github.com/open-mpi/ompi/wiki/SubmittingPullRequests) wiki page. In particular, note that all Git commits contributed to Open MPI require a "Signed-off-by" line.
57-
58-
## **Do you intend to add a new feature or change an existing one?**
59-
60-
* Suggest your change on the [devel mail list](https://www.open-mpi.org/community/lists/ompi.php) and start writing code. The [developer level technical information on the internals of Open MPI](https://www.open-mpi.org/faq/?category=developers) may also be useful for large scale features.
61-
62-
* Do not open an issue on GitHub until you have collected positive feedback about the change. GitHub issues are primarily intended for bug reports and fixes.
63-
64-
## **Do you have questions about the source code?**
65-
66-
* First checkout the [developer level technical information on the internals of Open MPI](https://www.open-mpi.org/faq/?category=developers). A paper describing the [multi-component architecture](https://www.open-mpi.org/papers/ics-2004/ics-2004.pdf) of Open MPI may also be helpful. The [devel mail list](https://www.open-mpi.org/community/lists/ompi.php) is a good place to post questions about the source code as well.
67-
68-
## Style
69-
70-
There are a small number of style rules for Open MPI:
71-
72-
1. For all code:
73-
* 4 space tabs. No more, no less.
74-
* No tab characters *at all*. 2 indentations are 8 spaces — not a tab.
75-
* m4 code is a bit weird in terms of indentation: we don't have a
76-
good, consistent indentation style in our existing code. But
77-
still: no tab characters at all.
78-
1. For C code:
79-
* We prefer if all blocks are enclosed in `{}` (even 1-line
80-
blocks).
81-
* We prefer that if you are testing equality with a constant, put
82-
the constant on the *left* of the `==`. E.g., `if (NULL ==
83-
ptr)`.
84-
* If there are no parameters to a C function, declare it with
85-
`(void)` (vs. `()`).
86-
87-
That's about it. Thank you!
88-
89-
— The Open MPI Team
16+
Please see the [Contributing
17+
guidelines](https://docs.open-mpi.org/en/main/contributing.html) for
18+
more details on how to contribute to Open MPI.

‎docs/contributing.rst

Lines changed: 130 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -6,78 +6,157 @@ There are many ways to contribute. Here are a few:
66
#. Subscribe to `the mailing lists
77
<https://www.open-mpi.org/community/lists/ompi.php>`_ and become
88
active in the discussions.
9-
#. Obtain `a Git clone <https://www.open-mpi.org/source/>`_ of Open
9+
10+
#. Obtain `a Git clone <https://github.com/open-mpi/ompi/>`_ of Open
1011
MPI's code base and start looking through the code.
1112

1213
.. note:: Be sure to see the :doc:`Developers guide
13-
</developers/index>` for technical details about the code
14-
base and how to build it).
14+
</developers/index>` for technical details about the
15+
code base and how to build it).
1516

16-
#. Write your own components and contribute them back to the main code
17-
base.
18-
#. Contribute bug fixes and feature enhancements to the main code
17+
#. Report bug fixes to the main code base.
18+
19+
* First, ensure the bug was not already reported by searching
20+
`existing GitHub Issues
21+
<https://github.com/open-mpi/ompi/issues>`_.
22+
* If you're unable to find an open issue addressing the problem,
23+
`open a new one <https://github.com/open-mpi/ompi/issues/new>`_.
24+
25+
#. Submit bug fixes to the main code base.
26+
27+
* Awesome! Open a new GitHub pull request with the patch.
28+
* Ensure the PR description clearly describes the problem and
29+
solution. If there is an existing GitHub issue open describing
30+
this bug, please include it in the description so we can track
31+
them together.
32+
* Be sure to see the :ref:`Open source contributions
33+
<contributing-open-source-label>` section, below.
34+
35+
#. Submit feature enhancements and/or new components to the main code
1936
base.
37+
38+
* Awesome! We love new ideas!
39+
* You might want to suggest your change on the `devel mail list
40+
<https://www.open-mpi.org/community/lists/ompi.php>`_ before you
41+
start writing code. The `developer level technical information
42+
on the internals of Open MPI
43+
<https://www.open-mpi.org/faq/?category=developers>`_ may also be
44+
useful for large scale features.
45+
* If you're contributing a large new piece of functionality, that
46+
will be best viewed if you |mdash| or someone, anyone |mdash| is
47+
also stepping up to help maintain that functionality over time.
48+
We love new ideas and new features, but we do need to be
49+
realistic in what we can reliably test and deliver to our users.
50+
* Be sure to see the :ref:`Open source contributions
51+
<contributing-open-source-label>` section, below.
52+
2053
#. Provide testing resources:
2154

2255
#. For Github Pull Request Continuous Integration (CI)
2356
#. For nightly snapshot builds and testing
2457

25-
2658
.. _contributing-open-source-label:
2759

2860
Open source contributions
2961
-------------------------
3062

31-
All code contributions are submitted as pull requests on the `Open MPI
32-
GitHub repository <https://github.com/open-mpi/ompi/>`_.
63+
All code contributions are submitted as pull requests on the `Open
64+
MPI GitHub repository <https://github.com/open-mpi/ompi/>`_.
65+
66+
.. important:: All commits must include a ``Signed-off-by:`` line,
67+
indicating the submitter's agreement to the :ref:`Open
68+
MPI Contributor's Declaration
69+
<contributing-contributors-declaration-label>`.
70+
71+
.. _contributing-contributors-declaration-label:
3372

34-
We need to have an established intellectual property pedigree of the
73+
Contributor's Declaration
74+
^^^^^^^^^^^^^^^^^^^^^^^^^
75+
76+
In order to ensure that we can keep distributing Open MPI under our
77+
:doc:`open source license </license/index>`, we need to ensure that
78+
all contributions are compatible with that license. Put differently:
79+
we need to have an established intellectual property pedigree of the
3580
code in Open MPI. This means being able to ensure that all code
3681
included in Open MPI is free, open source, and able to be distributed
3782
under :doc:`the BSD license </license/index>`.
3883

3984
Open MPI has therefore adopted requirements based on the signed-off-by
40-
process as described in the `Submitting patches
41-
<https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin>`_
42-
section of the Linux kernel documentation. Each proposed contribution
43-
to the Open MPI code base must include the text "Signed-off-by:"
44-
followed by the contributor's name and email address. This is a
45-
developer's certification that he or she has the right to submit the
46-
patch for inclusion into the project, and indicates agreement to the
47-
Developer's Certificate of Origin:
48-
49-
By making a contribution to this project, I certify that:
50-
51-
#. The contribution was created in whole or in part by me and I
52-
have the right to submit it under the Open MPI open source
53-
license; or
54-
55-
#. The contribution is based upon previous work that, to the best
56-
of my knowledge, is covered under an appropriate open source
57-
license and I have the right under that license to submit that
58-
work with modifications, whether created in whole or in part by
59-
me, under the Open MPI open source license (unless I am
60-
permitted to submit under a different license); or
61-
62-
#. The contribution was provided directly to me by some other
63-
person who certified (1) or (2) and I have not modified it.
64-
65-
#. I understand and agree that this project and the contribution
66-
are public and that a record of the contribution (including all
67-
personal information I submit with it, including my sign-off) is
68-
maintained indefinitely and may be redistributed consistent with
69-
this project and the open source license(s) involved.
70-
71-
Proposed contributions failing to include the "Signed-off-by:"
85+
process as described in Section 11 of the Linux kernel document on
86+
`Submitting Patches
87+
<https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin>`_.
88+
Each proposed contribution to the Open MPI code base must include the
89+
text ``Signed-off-by:`` followed by the contributor's name and email
90+
address. This is a developer's certification that he or she has the
91+
right to submit the patch for inclusion into the project, and
92+
indicates agreement to the Developer's Certificate of Origin:
93+
94+
By making a contribution to this project, I certify that:
95+
96+
#. The contribution was created in whole or in part by me and I
97+
have the right to submit it under the :doc:`Open MPI open
98+
source license </license/index>`; or
99+
100+
#. The contribution is based upon previous work that, to the best
101+
of my knowledge, is covered under an appropriate open source
102+
license and I have the right under that license to submit that
103+
work with modifications, whether created in whole or in part by
104+
me, under the :doc:`Open MPI open source license
105+
</license/index/>` (unless I am permitted to submit under a
106+
different license); or
107+
108+
#. The contribution was provided directly to me by some other
109+
person who certified (1) or (2) and I have not modified it.
110+
111+
#. I understand and agree that this project and the contribution
112+
are public and that a record of the contribution (including all
113+
personal information I submit with it, including my sign-off)
114+
is maintained indefinitely and may be redistributed consistent
115+
with this project and the open source license(s) involved.
116+
117+
Proposed contributions failing to include the ``Signed-off-by:``
72118
certification will not be accepted into any Open MPI code
73119
repository. The community reserves the right to revert any commit
74120
inadvertently made without the required certification.
75121

76-
This policy prevents a situation where intellectual property gets into
77-
the Open MPI code base and then someone later claims that we owe them
78-
money for it. Open MPI is a free, open source code base. We intend
79-
it to remain that way.
122+
.. note:: This policy prevents a situation where intellectual property
123+
gets into the Open MPI code base and then someone later
124+
claims that we owe them money for it. Open MPI is a free,
125+
open source code base. We intend it to remain that way.
126+
127+
If you have not already done so, please ensure that *every* commit in
128+
your pull request contains the ``Signed-off-by:`` line.
129+
130+
.. admonition:: Pro tip
131+
:class: tip
132+
133+
You can use the ``-s`` flag to the ``git commit`` command (i.e.,
134+
``git commit -s ...``) to automatically add the appropriate
135+
``Signed-off-by:`` line to your commit message.
136+
137+
Code style
138+
^^^^^^^^^^
80139

140+
There are a small number of style rules for Open MPI:
141+
142+
#. For all code:
143+
144+
* 4 space tabs. No more, no less.
145+
* No tab characters **at all**. 2 indentations are 8 spaces
146+
|mdash| not a tab.
147+
* m4 code is a bit weird in terms of indentation: we don't have a
148+
good, consistent indentation style in our existing code. But
149+
still: no tab characters at all.
150+
151+
#. For C code:
152+
153+
* We prefer if all blocks are enclosed in ``{}`` (even 1-line
154+
blocks).
155+
* We prefer that if you are testing equality with a constant, put
156+
the constant on the **left** of the ``==``. E.g., ``if (NULL ==
157+
ptr)``.
158+
* If there are no parameters to a C function, declare it with
159+
``(void)`` (vs. ``()``).
81160

82161
Closed source contributions
83162
---------------------------
@@ -89,9 +168,8 @@ from us. Such is the reality of software development in today's
89168
global economy.
90169

91170
As such, it is perfectly acceptable to make non-free / non-open-source
92-
contributions to Open MPI.
93-
94-
We obviously cannot accept such contributions into the main code base,
95-
but you are free to distribute plugins, enhancements, etc. as you see
96-
fit. Indeed, the :doc:`the BSD license </license/index>` is extremely
97-
liberal in its redistribution provisions.
171+
contributions to Open MPI. We obviously cannot accept such
172+
contributions into the main code base, but you are free to distribute
173+
plugins, enhancements, etc. as you see fit. Indeed, the :doc:`the BSD
174+
license </license/index>` is extremely liberal in its redistribution
175+
provisions.

‎docs/developers/rst-for-markdown-expats.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -98,16 +98,16 @@ Chapter and section delimiters
9898
.. code-block:: rst
9999
100100
Subsection 1: hello world
101-
-------------------------
101+
^^^^^^^^^^^^^^^^^^^^^^^^^
102102
103103
.. code-block:: rst
104104
105105
Subsubsection 1: hello world
106-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
106+
++++++++++++++++++++++++++++
107107
108108
Meaning: underlines made of ``=`` denotes chapters, underlines
109-
made of ``-`` denotes sections, underlines made of ``-`` denotes
110-
subsections, and underlines made of ``^`` denote subsubsections.
109+
made of ``-`` denotes sections, underlines made of ``^`` denotes
110+
subsections, and underlines made of ``+`` denote subsubsections.
111111

112112
Multi-line code/fixed-width font
113113
--------------------------------

0 commit comments

Comments
 (0)