diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 94fad78206d..f4c34ce6c8f 100644 --- a/CONTRIBUTING.md +++ b/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).