Revise Pull Request review process in CONTRIBUTING.md (#1119)

Revise our CONTRIBUTING.md documentation to be more clear
on all the steps from getting a Pull Request opened to being merged.

* Add a quick look at the issues
* Use nested lists for PR guidelines
* Use nested lists for Code Review
* Move Code Review to be within General guidelines
* Remove docstrings note in Cross-referencing with Sphinx
* Add reStructuredText tutorial in Documentation subsection
* Remove code review section
* Add some section links in Code Review
* Clarify that docs are mostly under the examples and pygmt folder

Co-authored-by: Yao Jiayuan <[email protected]>
Co-authored-by: Michael Grund <[email protected]>
Co-authored-by: Meghan Jones <[email protected]>
Co-authored-by: Dongdong Tian <[email protected]>

Author: 5 people

CONTRIBUTING.md

@@ -49,7 +49,6 @@ read it carefully.
   - [Testing your code](#testing-your-code)
   - [Testing plots](#testing-plots)
   - [Documentation](#documentation)
-  - [Code Review](#code-review)
 
 
 ## What Can I Do?
@@ -205,36 +204,73 @@ hesitate to [ask questions](#how-can-i-talk-to-you)):
 
 ### General guidelines
 
-We follow the [git pull request workflow](http://www.asmeurer.com/git-workflow/) to
-make changes to our codebase.
+We follow the [git pull request workflow](http://www.asmeurer.com/git-workflow)
+to make changes to our codebase.
 Every change made goes through a pull request, even our own, so that our
-[continuous integration](https://en.wikipedia.org/wiki/Continuous_integration) services
-have a change to check that the code is up to standards and passes all our tests.
+[continuous integration](https://en.wikipedia.org/wiki/Continuous_integration)
+services have a chance to check that the code is up to standards and passes all
+our tests.
 This way, the *master* branch is always stable.
 
-General guidelines for pull requests (PRs):
-
-* **Open an issue first** describing what you want to do. If there is already an issue
-  that matches your PR, leave a comment there instead to let us know what you plan to
-  do.
-* Each pull request should consist of a **small** and logical collection of changes.
-* Larger changes should be broken down into smaller components and integrated
-  separately. For example, break the wrapping of aliases into multiple pull requests.
-* Bug fixes should be submitted in separate PRs.
-* Use underscores for all Python (*.py) files as per [PEP8](https://www.python.org/dev/peps/pep-0008/),
-  not hyphens. Directory names should also use underscores instead of hyphens.
-* Describe what your PR changes and *why* this is a good thing. Be as specific as you
-  can. The PR description is how we keep track of the changes made to the project over
-  time.
-* Do not commit changes to files that are irrelevant to your feature or bugfix (eg:
-  `.gitignore`, IDE project files, etc).
-* Write descriptive commit messages. Chris Beams has written a
-  [guide](https://chris.beams.io/posts/git-commit/) on how to write good commit
-  messages.
-* Be willing to accept criticism and work on improving your code; we don't want to break
-  other users' code, so care must be taken not to introduce bugs.
-* Be aware that the pull request review process is not immediate, and is generally
-  proportional to the size of the pull request.
+General guidelines for making a Pull Request (PR):
+
+* What should be included in a PR
+  - Have a quick look at the titles of all the existing issues first. If there
+    is already an issue that matches your PR, leave a comment there to let us
+    know what you plan to do. Otherwise, **open an issue** describing what you
+    want to do.
+  - Each pull request should consist of a **small** and logical collection of
+    changes; larger changes should be broken down into smaller parts and
+    integrated separately.
+  - Bug fixes should be submitted in separate PRs.
+* How to write and submit a PR
+  - Use underscores for all Python (*.py) files as per
+    [PEP8](https://www.python.org/dev/peps/pep-0008/), not hyphens. Directory
+    names should also use underscores instead of hyphens.
+  - Describe what your PR changes and *why* this is a good thing. Be as
+    specific as you can. The PR description is how we keep track of the changes
+    made to the project over time.
+  - Do not commit changes to files that are irrelevant to your feature or
+    bugfix (e.g.: `.gitignore`, IDE project files, etc).
+  - Write descriptive commit messages. Chris Beams has written a
+    [guide](https://chris.beams.io/posts/git-commit/) on how to write good
+    commit messages.
+* PR review
+  - Be willing to accept criticism and work on improving your code; we don't
+    want to break other users' code, so care must be taken not to introduce
+    bugs.
+  - Be aware that the pull request review process is not immediate, and is
+    generally proportional to the size of the pull request.
+
+#### Code Review
+
+After you've submitted a pull request, you should expect to hear at least a
+comment within a couple of days. We may suggest some changes, improvements or
+alternative implementation details.
+
+To increase the chances of getting your pull request accepted quickly, try to:
+
+* Submit a friendly PR
+  - Write a good and detailed description of what the PR does.
+  - Write some documentation for your code (docstrings) and leave comments
+    explaining the *reason* behind non-obvious things.
+  - Write tests for the code you wrote/modified if needed.
+    Please refer to [Testing your code](#testing-your-code) or
+    [Testing plots](#testing-plots).
+  - Include an example of new features in the gallery or tutorials.
+    Please refer to [Gallery plots](#gallery-plots) or [Tutorials](#tutorials).
+* Have a good coding style
+  - Use readable code, as it is better than clever code (even with comments).
+  - Follow the [PEP8](http://pep8.org) style guide for code and the
+    [numpy style guide](https://numpydoc.readthedocs.io/en/latest/format.html)
+    for docstrings. Please refer to [Code style](#code-style).
+
+Pull requests will automatically have tests run by GitHub Actions.
+This includes running both the unit tests as well as code linters.
+GitHub will show the status of these checks on the pull request.
+Try to get them all passing (green).
+If you have any trouble, leave a comment in the PR or
+[get in touch](#how-can-i-talk-to-you).
 
 ### Setting up your environment
 
@@ -510,11 +546,17 @@ def test_my_plotting_case():
 
 ### Documentation
 
+Most documentation sources are in Python `*.py` files under the `examples/`
+folder, and the code docstrings can be found e.g. under the `pygmt/src/` and
+`pygmt/datasets/` folders. The documentation are written in
+[reStructuredText](https://docutils.sourceforge.io/rst.html) and
+built by [Sphinx](http://www.sphinx-doc.org/). Please refer to
+[reStructuredText Cheatsheet](https://docs.generic-mapping-tools.org/latest/rst-cheatsheet.html)
+if you are new to reStructuredText.
+
 #### Building the documentation
 
-Most documentation sources are in the `doc` folder.
-We use [sphinx](http://www.sphinx-doc.org/) to build the web pages from these sources.
-To build the HTML files:
+To build the HTML files from sources:
 
 ```bash
 cd doc
@@ -560,33 +602,3 @@ https://docs.generic-mapping-tools.org/latest/gmt.conf.html#term-COLOR_FOREGROUN
 
 Sphinx will create a link to the automatically generated page for that
 function/class/module.
-
-**All docstrings** should follow the
-[numpy style guide](https://numpydoc.readthedocs.io/en/latest/format.html).
-All functions/classes/methods should have docstrings with a full description of all
-arguments and return values.
-
-### Code Review
-
-After you've submitted a pull request, you should expect to hear at least a comment
-within a couple of days.
-We may suggest some changes or improvements or alternatives.
-
-Some things that will increase the chance that your pull request is accepted quickly:
-
-* Write a good and detailed description of what the PR does.
-* Write tests for the code you wrote/modified.
-* Readable code is better than clever code (even with comments).
-* Write documentation for your code (docstrings) and leave comments explaining the
-  *reason* behind non-obvious things.
-* Include an example of new features in the gallery or tutorials.
-* Follow the [PEP8](http://pep8.org) style guide for code and the
-  [numpy guide](https://numpydoc.readthedocs.io/en/latest/format.html)
-  for documentation.
-
-Pull requests will automatically have tests run by GitHub Actions.
-This includes running both the unit tests as well as code linters.
-GitHub will show the status of these checks on the pull request.
-Try to get them all passing (green).
-If you have any trouble, leave a comment in the PR or
-[get in touch](#how-can-i-talk-to-you).