From e2ecd6ad92f757c0c61c99500a3bed360016734a Mon Sep 17 00:00:00 2001 From: Brent Huisman <brenthuisman@users.noreply.github.com> Date: Wed, 8 Dec 2021 15:43:01 +0100 Subject: [PATCH] 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 | 67 ++++++++++++++++++++++++++++++++++++++++++++ doc/contrib/test.rst | 2 +- 2 files changed, 68 insertions(+), 1 deletion(-) diff --git a/doc/contrib/pr.rst b/doc/contrib/pr.rst index 1d98cb7f..c22c59cd 100644 --- a/doc/contrib/pr.rst +++ b/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 diff --git a/doc/contrib/test.rst b/doc/contrib/test.rst index e447931c..54fcc358 100644 --- a/doc/contrib/test.rst +++ b/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 -- GitLab