From ce945f2085d1c3d7b7ca03f0128695c1a30a43df Mon Sep 17 00:00:00 2001
From: Brent Huisman <brenthuisman@users.noreply.github.com>
Date: Thu, 10 Dec 2020 16:52:08 +0100
Subject: [PATCH] Move contrib documentation to right place. (#1268)
* Move PR message instructions to 'Making a PR' section.
* Move coding instructions to 'Write code' section.
---
doc/contrib/index.rst | 11 +++++++++-
doc/contrib/pr.rst | 48 +++++++++++++++++++------------------------
2 files changed, 31 insertions(+), 28 deletions(-)
diff --git a/doc/contrib/index.rst b/doc/contrib/index.rst
index 8ac99092..1f0a0546 100644
--- a/doc/contrib/index.rst
+++ b/doc/contrib/index.rst
@@ -73,7 +73,16 @@ request.
Write code
~~~~~~~~~~
-See :ref:`contribpr`.
+Some tips when contributing code:
+
+- Consider the :ref:`contribcodingstyle`.
+- If you add functionality, please update the documentation
+ accordingly.
+- If you add functionality, add tests if applicable. This helps make
+ sure Arbor is stable and functionality does what it’s supposed to
+ do.
+- If you work on the public C++ API, provide Python wrappings.
+- Make sure Arbor compiles and has no new warnings.
Add examples or unit tests
~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/contrib/pr.rst b/doc/contrib/pr.rst
index b3d8fcd1..89b0945f 100644
--- a/doc/contrib/pr.rst
+++ b/doc/contrib/pr.rst
@@ -11,15 +11,30 @@ Making a pull request
If you want to contribute code that implements a solution or feature,
the workflow is as follows:
-1. Fork the Arbor repository
-2. Create a branch off of master and implement your feature
+1. Fork the Arbor repository.
+2. Create a branch off of master and implement your feature.
3. Make a pull request (PR) and refer to the issue(s) that the PR
- addresses.
+ addresses. Some tips on how to write a good PR description:
+
+ - You can use labels to categorize your PR. For very large PRs, it
+ is likely the reviewer will have many questions and comments. It
+ can be helpful to reach out on our Slack, Discussions or by email
+ beforehand if you’ve big things planned for Arbor!
+ - Commit logical units with clear commit messages.
+ - Add a change summary to the PR message. If you remembered to commit
+ logical units, this could simply be a bulleted list of all commit
+ messages in the PR. If during the review process you make changes
+ to the features in the PR, keep the PR description updated.
+ - Use text like `fixes #123` in the description to refer to an issue.
+
4. An administrative matter: we request that you grant us a right of use on your contribution.
Please contact us at `arbor-sim@fz-juelich.de <mailto:arbor-sim@fz-juelich.de>`__.
-5. A PR on Github is automatically tested by our CI bot called Travis.
+5. A PR on Github is automatically built and tested by our CI bot called Travis.
You can also run these tests yourself by building them first
(``make tests``) and then running them (``./bin/*unit*``).
+
+ - If you make changes effecting simulations on GPUs, you can post a reply to
+ your PR with ``bors try``. This will run our GPU test-suite.
6. A member of the Arbor development team will review your contribution.
If they approve, your PR will be merged! Normally this should happen
within a few days.
@@ -36,32 +51,11 @@ Reviewing a PR
Each pull request is reviewed according to these guidelines:
- At least one core Arbor team member needs to mark your PR with a
- positive review. Some tips to help you get a positive review:
-
- - You can use labels to categorize your PR. For very large PRs, it
- is likely the reviewer will have many questions and comments. It
- can be helpful to reach out on our Slack, Discussions or by email
- beforehand if you’ve big things planned for Arbor!
- - Commit logical units with clear commit messages.
- - Add change summary to the PR message. If you remembered to commit
- logical units, this could simply be a bulleted list of all commit
- messages in the PR. If during the review process you make changes
- to the features in the PR, keep the PR description updated.
- - Make sure your code conforms to our `coding
- guidelines <https://github.com/arbor-sim/arbor/wiki/Coding-Style-Guidelines>`__
- - If you add functionality, please update the documentation
- accordingly.
- - If you add functionality, add tests if applicable. This helps make
- sure Arbor is stable and functionality does what it’s supposed to
- do.
- - If you make changes to GPU simulations, you can post a reply to
- your PR with ``bors try``. This will run our GPU test-suite.
- - If you add/change the public C++ API, provide Python wrappings.
- - Make sure Arbor compiles and has no new warnings.
-
+ positive review.
- Travis CI must produce a favourable result on your PR.
- An Arbor team member will (squash) merge the PR with the PR change
summery as commit message.
+- Consider using Gitpod to review larger PRs, see under checks on the Github PR page.
.. _contribpr-merge:
--
GitLab