Docs/contrib updates (#1736)

* Add documentation for collaboration on a PR using just git
* Add the stage of Issue creation to PR workflow.
* Correct header level in test docs

doc/contrib/pr.rst

@@ -3,6 +3,23 @@
 PR workflow
 ===========
 
+The PR, short for Github Pull Request, is a way to merge code on Github, where the main Arbor-repo is hosted.
+
+.. _contribpr-issue:
+
+Issues
+------
+
+New features, bugfixes or other kinds of contributions ideally start their lives as an Issue (short for Github Issue)
+on our `Issue tracker <https://github.com/arbor-sim/arbor/issues>`_. We distinguish two broad categories of
+issues: feature requests to add new functionality to arbor and bugs pointing out mistakes, inaccuracies,
+and plain faults in Arbor. Having a formal Github Issue before an implementation addressing a request or bug
+(as a PR containing a code contribution or otherwise) gives others the chance to weigh in and help
+find a solution that fits Arbor and its design, which makes it easier to integrate your contribution.
+Especially for new features, this is a helpful process. Have a look at our
+`blogpost on this subject <https://arbor-sim.org/how-to-file-an-issue/>`_ for some more rationale for
+this process.
+
 .. _contribpr-make:
 
 Making a pull request
@@ -48,6 +65,56 @@ Refer to the `Github
 documentation <https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request>`__
 for more explanation of the Git workflow described above.
 
+.. _contribpr-collab:
+
+Collaborating on a PR
+---------------------
+
+Especially for larger PRs, it may be a good idea to collaborate with others. There are various ways to do so,
+for instance to have a shared branch somewhere in a fork of the Arbor repo. Since we're using Github, you can
+also add commits to a PR opened by someone else. Since the correct procedure for that is 
+`Github specific <https://docs.github.com/en/github/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork>`_,
+here the steps for how to do this (with just ``git``).
+
+Alongside the instruction, an example situation will be given. Here, it is assumed that you've created your own
+Github fork of the Arbor repo, and that you have this cloned to disk (and the ``origin`` remote points to your
+fork of Arbor on Github). We'll setup a new remote called ``upstream``, pointing to the ``arbor-sim/arbor`` repo.
+The example situation is that you want to commit to pull request number ``321``, opened by a 
+Github user called ``github_user_007``, who named the branch they're trying to merge ``my_special_branch``,
+in their fork of the Arbor repo called ``arbor-sim`` (which is the default when you fork on Github).
+
+Situation as a table
+~~~~~~~~~~~~~~~~~~~~
+
+=============================== ========================= ======================
+description                     variable                  example
+remote for Arbor main repo      ``$REMOTE``               ``upstream``
+PR you want to contribute to    ``$PR``                   ``321``
+Github user that opened the PR  ``$PR_AUTHOR``            ``github_user_007``
+branch name of the PR           ``$REMOTE_BRANCH_NAME``   ``my_special_branch``
+repo name of the above branch   ``$REPO``                 ``arbor-sim``
+=============================== ========================= ======================
+
+Steps
+~~~~~
+
+0. Add the ``upstream`` remote like so:
+   ``git remote add upstream https://github.com/arbor-sim/arbor``
+1. ``git fetch $REMOTE pull/$PR/head:$REMOTE_BRANCH_NAME``
+
+   Example: ``git fetch upstream pull/321/head:my_special_branch``
+2. This should have made a local branch with the same name, tracking the PR-branch. Switch to the new local branch.
+
+   Example: ``git switch my_special_branch``
+3. Make commits to that local branch.
+4. Push to the PR-branch with the following incantation:
+   ``git push git@github.com:$PR_AUTHOR/$REPO $LOCAL_BRANCH_NAME:$REMOTE_BRANCH_NAME``
+
+   Example: ``git push git@github.com:github_user_007/arbor-sim my_special_branch:my_special_branch``
+5. The commit should now show up on the PR. When the PR is going to be merged, Github will add a
+   "Co-authored by ..." line to the commit body. Leaving this line in place upon merging, will then list
+   these contributors in Github UI.
+
 .. _contribpr-review:
 
 Reviewing a PR

doc/contrib/test.rst

@@ -7,7 +7,7 @@ C++ tests are located in ``/tests`` and Python (binding) tests in ``/python/test
 See the documentation on :ref:`building <building>` for the C++ tests and ``/python/test/readme.md`` for the latter.
 
 Python tests
-============
+------------
 
 The Python tests uses the `unittest
 <https://docs.python.org/3/library/unittest.html>`_ and its test discovery