A variety of docs updates

docs/building-apps/building-static-apps.rst

@@ -1,3 +1,5 @@
+.. _label-building-fully-static-apps:
+
 Building fully-static MPI applications
 ======================================
 

docs/building-apps/extracting-wrapper-flags.rst

@@ -23,7 +23,7 @@ that will show what commands would have been invoked.
    shell$ mpicc --showme
 
 .. note:: If you pass ``--showme`` *and additional command line
-   parameters* to the wrapper compiler, sure to *also* pass in a
+   parameters* to the wrapper compiler, be sure to *also* pass in a
    filename.  Otherwise, the ``--showme`` functionality will not
    display output as expected.
 

docs/building-apps/quickstart.rst

@@ -17,16 +17,20 @@ probably work in many environments.
 Open MPI provides "wrapper" compilers that should be used for
 compiling MPI and OpenSHMEM applications:
 
-+---------+--------------------------+
-| C       | ``mpicc``, ``oshcc``     |
-+---------+--------------------------+
-| C++     | ``mpiCC``, ``oshCC`` (or |
-|         | ``mpic++`` if your       |
-|         | filesystem is            |
-|         | case-insensitive)        |
-+---------+--------------------------+
-| Fortran | ``mpifort``, ``oshfort`` |
-+---------+--------------------------+
++---------+-----------------------------------+
+| C       | :ref:`mpicc(1) <man1-mpicc>`,     |
+|         | :ref:`oshcc(1) <man1-oshcc>`      |
++---------+-----------------------------------+
+| C++     | :ref:`mpic++(1) <man1-mpic++>`,   |
+|         | :ref:`oshc++(1) <man1-oshc++>`    |
+|         | (and :ref:`mpiCC(1) <man1-mpiCC>` |
+|         | and :ref:`oshCC(1) <man1-oshCC>`  |
+|         | if you filesystem is              |
+|         | case-sensitive)                   |
++---------+-----------------------------------+
+| Fortran | :ref:`mpifort(1) <man1-mpifort>`, |
+|         | :ref:`oshfort(1) <man1-oshfort>`  |
++---------+-----------------------------------+
 
 .. caution:: The legacy names ``mpif77`` and ``mpif90`` still exist,
              and are simply symbolic links to the ``mpifort`` wrapper

docs/contributing.rst

@@ -25,6 +25,12 @@ There are many ways to contribute.  Here are a few:
 #. Submit bug fixes to the main code base.
 
    * Awesome!  Open a new GitHub pull request with the patch.
+
+     * Please submit bug fixes / new features on the ``main`` branch
+       first, and then port them to the relevant release branch(es)
+       after they have been accepted on ``main``.  :ref:`See this
+       section for more information <git-github-branch-scheme-label>`.
+
    * 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 track
@@ -50,6 +56,18 @@ There are many ways to contribute.  Here are a few:
    * Be sure to see the :ref:`Open source contributions
      <contributing-open-source-label>` section, below.
 
+#. Submit fixes and/or entirely new content to this documentation.
+
+   * Docs are great!  We always need help with documentation.
+   * These docs are authored using ReStructured Text markup with the
+     Sphinx rendering tool under the ``docs/`` directory in the
+     repository.  This means you can submit a pull request with your
+     docs updates, just like you would for any Open MPI code contribution.
+   * :ref:`See this section <developers-installing-sphinx-label>` and
+     :ref:`also this section <developers-rst-for-markdown-expats>` for
+     information about how to install Sphinx locally and some
+     high-level logistical instructions on how to write these docs.
+
 #. Provide testing resources:
 
    #. For Github Pull Request Continuous Integration (CI)

docs/developers/git-github.rst

@@ -0,0 +1,196 @@
+GitHub, Git, and related topics
+===============================
+
+GitHub
+------
+
+Open MPI's Git repositories are `hosted at GitHub
+<https://github.com/open-mpi/ompi>`_.
+
+#. First, you will need a Git client. We recommend getting the latest
+   version available. If you do not have the command ``git`` in your
+   path, you will likely need to download and install Git.
+#. `ompi <https://github.com/open-mpi/ompi/>`_ is the main Open MPI
+   repository where most active development is done.  Git clone this
+   repository.  Note that the use of the ``--recursive`` CLI option is
+   necessary because Open MPI uses Git submodules::
+
+      shell$ git clone --recursive https://github.com/open-mpi/ompi.git
+
+Note that Git is natively capable of using many forms of web
+proxies. If your network setup requires the user of a web proxy,
+`consult the Git documentation for more details
+<https://git-scm.com/>`_.
+
+Git commits: open source / contributor's declaration
+----------------------------------------------------
+
+In order to remain open source, all new commits to the Open MPI
+repository must include a ``Signed-off-by:`` line, indicating the
+submitter's agreement to the :ref:`Open MPI Contributor's Declaration
+<contributing-contributors-declaration-label>`.
+
+.. tip:: You can use the ``-s`` option to ``git commit`` to
+         automatically add the ``Signed-off-by:`` line to your commit
+         message.
+
+.. _git-github-branch-scheme-label:
+
+Git branch scheme
+-----------------
+
+Generally, Open MPI has two types of branches in its Git repository:
+
+#. ``main``:
+
+   * All active development occurs on the ``main`` branch (new features,
+     bug fixes, etc.).
+
+#. Release branches of the form ``vMAJOR.MINOR.x`` (e.g., ``v4.0.x``,
+   ``v4.1.x``, ``v5.0.x``).
+
+   * The ``.x`` suffix indicates that this branch is used to create
+     all releases in the Open MPI vMAJOR.MINOR series.
+   * Periodically, the Open MPI community will make a new release
+     branch, typically from ``main``.
+   * A Git tag of the form ``vMAJOR.MINOR.RELEASE`` is used to
+     indicate the specific commit on a release branch from where
+     official Open MPI release tarball was created (e.g., ``v4.1.0``,
+     ``v4.1.1``, ``v4.1.2``, etc.).
+
+Once a bug is fixed or a new feature is implemented on ``main``, it is
+cherry-picked over to the relevant release branch(es).
+
+.. attention:: It may seem odd to some, but the Open MPI community
+               development model does *not* PR bug fixes or new
+               features directly to release branches.  Instead,
+               initial bug-fix / feature PRs are generally first made
+               to ``main``.
+
+               This helps us ensure that future releases (with
+               ``main`` as a Git ancestor) will contain the bug fix /
+               feature.
+
+For example:
+
+.. code:: sh
+
+   shell$ git checkout main
+   shell$ git pull --rebase
+   shell$ git checkout pr/bug-fix
+
+   # ... make changes / fix a bug / etc. ...
+
+   shell$ git add ...
+   shell$ git commit -s ...
+   shell$ git push myfork
+
+At this point, you go create a PR from your fork's ``pr/bug-fix``
+branch to the Open MPI community GitHub repo ``main`` branch.  Work
+with the community to get the PR completed and merged.  Then you can
+open a new PR to cherry pick the Git commits from that bug fix to each
+of the relevant release branches.
+
+Depending on how far the release branch has diverged from ``main``,
+there may be some porting effort involved in the cherry-pick.
+
+For example, if your bug fix on ``main`` is comprised of a single Git
+commit hash ``123abc``:
+
+.. code:: sh
+
+   # Fetch all upstream git activity, including the merge of the "main" PR.
+   shell$ get fetch --all
+
+   # Check out the target release branch, and advance to the most recent commit.
+   shell$ git checkout v5.0.x
+   shell$ git pull --rebase
+
+   # Make a branch for your bug fix
+   shell$ git checkout -b pr/v5.0.x/bug-fix
+   # Cherry pick the commit from the "main" branch
+   shell$ git cherry-pick -x 123abc
+   # Push to your fork
+   shell$ git push myfork
+
+The Open MPI development community *requires* adding the following
+line to the commit message of cherry-picked commits on release
+branches:
+
+.. code:: text
+
+   (cherry picked from commit [git_hash_of_original_commit])
+
+.. note:: Note the use of the ``-x`` option to ``git cherry-pick``.
+          This option automatically adds the ``(cherry picked from
+          ...)`` line to your commit message.
+
+.. admonition:: Rationale
+   :class: tip
+
+   Git does not actually store any meta data about Git cherry-picks in
+   the commit.  Having a standardized text line containing the source
+   Git commit hash in the commit messages helps the Open MPI
+   development community track where commits came from on release
+   branches, and therefore allows us to check whether all relevant
+   commits have been ported to a given release branch.
+
+Once your commits are ready and pushed up to your fork, make a PR to
+the target release branch.
+
+.. warning:: A GitHub PR CI job checks all commits on release branches
+             for the ``(cherry picked from...)`` line. It will also
+             ensure that the Git hash cited in that line actually
+             exists on the ``main`` branch.
+
+             This check ensures that commits are not made to release
+             branches before their corresponding ``main`` PR was
+             merged.
+
+All this being said, sometimes there is a need for a non-cherry-picked
+commit on a release branch. E.g., sometimes a release branch has
+diverged so much that the bug no longer exists on ``main``.  It would
+therefore not make sense |mdash| or even be impossible |mdash| to
+commit the bug fix in question to ``main``.
+
+In such cases, make a regular PR to the target branch (with commits
+that do *not* include ``(cherry picked from ...)`` lines).  In the PR
+description, add a line with the following token:
+
+.. code:: text
+
+   bot:notacherrypick
+
+This tells the GitHub CI job that this PR contains commits that are
+not cherry-picked from ``main``.
+
+.. warning:: ``bot:notacherrypick`` should only be used when
+             absolutely necessary.  It is not a license to avoid
+             the process of PR'ing to ``main`` first.
+
+CI (testing)
+------------
+
+The Open MPI community generally runs two flavors of testing:
+
+#. A bunch of tests on each PR (Continuous Integration / CI).  These
+   tests are a mixture of GitHub Actions and other CI systems (e.g.,
+   Jenkins).  Examples include (but are not limited to):
+
+   * Check each Git commit for bozo email addresses
+   * Check that each Git commit contains a ``Signed-off-by`` line
+   * Check that commits on release branches contain a cherry-pick
+     notice
+   * Build and publish the docs
+   * Build Open MPI in a variety of environments and run sanity tests
+     with that installation
+
+#. Daily testing via the MPI Testing Tool (MTT).
+
+   * These are generally tests that take much longer to run than on a
+     per-PR basis.  `A "nightly snapshot" tarball
+     <https://www.open-mpi.org/nightly/>`_ is created for ``main`` and
+     each relevant release branch.
+   * MTT tests are run with this snapshot tarball so that all
+     organizations are testing with the same snapshots.
+   * `Results are available here <https://mtt.open-mpi.org/>`_.

docs/developers/index.rst

@@ -12,7 +12,7 @@ probably don't need to read this section.
    :maxdepth: 1
 
    prerequisites
-   git-clone
+   git-github
    compiler-pickyness
    autogen
    building-open-mpi

docs/developers/prerequisites.rst

@@ -47,6 +47,14 @@ build them manually, see the :ref:`how to build and install GNU
 Autotools section <developers-installing-autotools-label>` for much
 more detail.
 
+Perl
+----
+
+Open MPI still uses Perl for a few of its build scripts (most notably,
+``autogen.pl``).
+
+Generally speaking, any recent-ish release of Perl 5 should be
+sufficient to correctly execute Open MPI's Perl scripts.
 
 Flex
 ----
@@ -80,12 +88,12 @@ MacPorts on MacOS), see `the Flex Github repository
 <https://github.com/westes/flex>`_.
 
 
-Sphinx
-------
+Sphinx (and therefore Python)
+-----------------------------
 
-`Sphinx <https://www.sphinx-doc.org/>`_ is used to generate both the
-HTML version of the documentation (that you are reading right now) and
-the nroff man pages.
+`Sphinx <https://www.sphinx-doc.org/>`_ is a Python-based tool used to
+generate both the HTML version of the documentation (that you are
+reading right now) and the nroff man pages.
 
 Official Open MPI distribution tarballs contain pre-built HTML
 documentation and man pages.  This means that -- similar to the GNU

docs/developers/source-code.rst

@@ -79,18 +79,23 @@ C / C++
   * In Open MPI, we **always** ``#define`` a logical macro to be
     either 0 or 1 -- we never ``#undef`` it.
   * The reason for this is defensive programming: if you are only
-    checking if a preprocessor macro is defined (via ``#ifdef`` or
-    ``"#if`` defined(FOO)"), you will get no warning when compiling if
+    checking if a preprocessor macro is defined (via ``#ifdef FOO`` or
+    ``#if defined(FOO)``), you will get no warning when compiling if
     you accidentally misspell the macro name.  However, if you use the
     logic test ``#if FOO`` with an undefined macro (e.g., because you
     misspelled it), you'll get a compiler warning or error.
-    Misspelled macro names can be tremendously difficult to find when
-    they are buried in thousands of lines of code, so we will take all
-    the help from the preprocessor/compiler that we can get!
+
+    .. admonition:: Rationale
+       :class: tip
+
+       Misspelled macro names can be tremendously difficult to find
+       when they are buried in thousands of lines of code; we will
+       take all the help from the preprocessor/compiler that we can
+       get!
 
   .. code-block:: c
 
-     /* Gnu Way - you will get no warning from the compiler if you
+     /* GNU Way - you will get no warning from the compiler if you
         misspell "FOO"; the test will simply be false */
      #ifdef FOO
      ...
@@ -155,18 +160,6 @@ and try to use a similar style.
      # This is good
      if test "$foo" = "bar"; then
 
-* Do not use the ``-a`` or ``-o`` operators for ``test`` |mdash| this
-  has caused portability problems with ``test(1)`` on BSD systems.
-  Instead, use the ``&&`` or ``||`` shell operators.
-
-  .. code-block:: sh
-
-     # This is bad
-     if test "$foo" = "bar" -a "$baz" = "yow"; then
-
-     # This is good
-     if test "$foo" = "bar" && test "$baz" = "yow"; then
-
 m4
 ^^^