diff --git a/docs/source/contribute.rst b/docs/source/contribute.rst new file mode 100644 index 0000000000..0b63e2b66f --- /dev/null +++ b/docs/source/contribute.rst @@ -0,0 +1,47 @@ +.. _contribute: + +Contributing to Cartopy +======================= + +Cartopy is an open-source project that welcomes contributions from anyone. A good place +to start contributing is by fixing typos, adding examples, or improving the explanations +of the functions. + +To contribute new features or bug fixes, you can create a pull request with your code changes +on GitHub. The easiest way to get started contributing code is to clone the repository to your +local system and install the conda development environment included with the source code. + +.. code:: + + git clone git@github.com:YOUR-USERNAME/cartopy.git + cd cartopy + + conda env create -f environment.yml + conda activate cartopy-dev + +This will install all of the required dependencies for compiling the code, running the tests, and +building the documentation. Remember to activate the `cartopy-dev` environment. + +A development and test workflow may look something like the following code block. + +.. code:: + + # Activate your development environment + conda activate cartopy-dev + + # Checkout a new feature branch + git checkout -b my-cool-feature + + # Make your code changes here, including tests for the changes! + # add and commit the changes with a useful commit message + # describing what changes you made + git add lib/cartopy/my-changed-file.py + git commit + + # Test your code on 4 processors + pytest -n 4 lib/cartopy + + # push your changes to your GitHub account + git push --set-upstream origin my-coll-feature + + # Go to GitHub and make a Pull Request to Cartopy diff --git a/docs/source/getting_started/index.rst b/docs/source/getting_started/index.rst index ba17ca2304..d844196bb9 100644 --- a/docs/source/getting_started/index.rst +++ b/docs/source/getting_started/index.rst @@ -28,6 +28,7 @@ attributions for data, and becoming a contributor on the project. .. toctree:: + ../contribute ../citation ../copyright ../contributors diff --git a/docs/source/index.rst b/docs/source/index.rst index b6526c16a2..d41e34fb8f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -49,5 +49,5 @@ There are many ways to get involved in the development of cartopy: * Contribute to the documentation fixing typos, adding examples, explaining things more clearly, or even re-designing its layout/logos etc. The `documentation source `_ is kept in the same repository as the source code. * Contribute bug fixes (:issues:`a list of outstanding bugs can be found on GitHub `). - * Contribute enhancements and new features on the issue tracker. + * :ref:`contribute` describes some simple steps to get started when contributing code to Cartopy. * Chat with users and developers in the `Gitter chat room `_.