Contribution guide

Contribution guide

Contributions of any size are highly welcomed and highly appreciated! You can make a high impact on ProPlot just by using it and reporting issues.

The following sections cover some general guidelines regarding development in ProPlot for maintainers and contributors. Feel free to suggest improvements or changes in the workflow.

Feature requests and feedback

We are eager to hear your requests for new features, suggestions regarding the current API, and so on. You can submit these as issues on Github. Please make sure to explain in detail how the feature should work and keep the scope as narrow as possible. This will make it easier to implement in small pull requests.

If you are feeling inspired, feel free to add the feature yourself and submit a pull request!

Report bugs

Bugs should be reported on the Github issues page. When reporting a bug, please follow the template message and include copy-pasteable code that reproduces the issue. This is critical for developers to fix the bug quickly.

If you can figure out how to fix the bug yourself, feel free to submit a pull request.

Write tests

Most modern python packages have test_*.py scripts that are run by pytest via the Travis Continuous Integration service whenever commits are pushed to the repository. Currently, ProPlot only tests the examples that appear on the website User Guide (see travis.yml). While we try to make the examples comprehensive, this approach leaves out a lot of use cases and leaves the project more vulnerable to bugs. Adding tests is a critical item on our to-do list.

If you can think of a useful test for ProPlot, feel free to submit a pull request. Your test will be used in the future.

Write documentation

Documentation can always be improved. For minor changes, you can edit docstrings and documentation files directly in the GitHub web interface without using a local copy.

The docstrings are written in reStructuredText with numpydoc style headers. They are embedded in the API reference section using a fork of sphinx-automodapi.
Other sections are written using .rst and files and .py files (translated to python notebooks via jupytext) in the docs folder. The notebooks are embedded in the User Guide using nbsphinx.
The default ReST role is py:obj. Please include py:obj links whenever discussing particular functions or classes – for example, if you are discussing the format method, please write `~proplot.axes.Axes.format` rather than format. ProPlot also uses intersphinx so you can link to external packages like matplotlib and cartopy.

To build the documentation locally, use the following commands:

cd docs
# Install dependencies to the base conda environment..
conda env update -f environment.yml
# ...or create a new conda environment
# conda env create -n proplot-dev --file docs/environment.yml
# source activate proplot-dev
# Create HTML documentation
make html

The built documentation should be available in docs/_build/html.

Preparing pull requests

Here is a quick guide for submitting pull requests:

Fork the proplot GitHub repository. It’s fine to keep “proplot” as the fork repository name because it will live under your account.
Clone your fork locally using git, connect your repository to the upstream (main project), and create a branch as follows:
```
git clone git@github.com:YOUR_GITHUB_USERNAME/proplot.git
cd proplot
git remote add upstream git@github.com:lukelbd/proplot.git
git checkout -b your-branch-name master
```
If you need some help with git, follow the quick start guide.
Make an editable install of ProPlot by running:
```
pip install -e .
```
This way import proplot imports your local copy, rather than the stable version you last downloaded from PyPi. You can import proplot; print(proplot.__file__) to verify your local copy has been imported.
Install pre-commit and its hook on the proplot repo as follows:
```
pip install --user pre-commit
pre-commit install
```
Afterwards pre-commit will run whenever you commit. pre-commit is a framework for managing and maintaining multi-language pre-commit hooks to ensure code-style and code formatting is consistent.
You can now edit your local working copy as necessary. Please follow the PEP8 style guide. and try to generally adhere to the black subset of the PEP8 style (we may automatically enforce the “black” style in the future). When committing, pre-commit will modify the files as needed, or will generally be clear about what you need to do to pass the pre-commit test.

Please break your edits up into reasonably sized commits:
```
git commit -a -m "<commit message>"
git push -u
```
The commit messages should be short, sweet, and use the imperative mood, e.g. “Fix bug” instead of “Fixed bug”.
If you intend to make changes or add examples to the user guide, you may want to open the docs/*.py files as jupyter notebooks. This can be done by installing jupytext, starting a jupyter session, and clicking on the .py files in the Files page.
When you’re finished, create a new changelog entry in CHANGELOG.rst. The entry should be entered as:
```
<description> (:pr:`<PR number>`) `<author name>`_
```
where <description> is the description of the PR related to the change, <PR number> is the pull request number, and <author name> is your first and last name. Add yourself to list of authors at the end of CHANGELOG.rst if not there, in alphabetical order.

Make sure to add the changelog entry under one of the valid .. rubric:: <heading> headings listed at the top of CHANGELOG.rst.

Finally, submit a pull request through the GitHub website using this data:

head-fork: YOUR_GITHUB_USERNAME/proplot
compare: your-branch-name
base-fork: lukelbd/proplot
base: master

Note that you can create the pull request before you’re finished with your feature addition or bug fix. The PR will update as you add more commits. ProPlot developers and contributors can then review your code and offer suggestions.

Release procedure

Once version 1.0 is released, ProPlot will follow semantic versioning, with version numbers that look like vX.Y.Z. A major version (X) causes incompatible API changes, a minor version (Y) adds functionality, and a patch (Z) covers bug fixes. But these are not strict rules – more like guidelines. Currently, ProPlot’s major version number is 0, reflecting the fact that the API is new and subject to rapid changes (although we try to make sure the changes are not without warning).

For now, Luke Davis is the only one who can publish releases on PyPi, but this will change in the future. Releases should be carried out as follows:

Create a new branch release-vX.Y.Z with the version for the release. In this branch, update CHANGELOG.rst, and make sure all new changes are reflected in the documentation:
```
git add CHANGELOG.rst
git commit -m "Changelog updates"
```
Open a new pull request for this branch targeting master.
After all tests pass and the pull request has been approved, merge into master.
Get the latest version of the master branch:
```
git checkout master
git pull
```

Tag the current commit and push to github:

git tag -a vX.Y.Z -m "Version X.Y.Z"
git push origin master --tags

Build and publish release on PyPI:

# Remove previous build products and build the package
rm -r dist build *.egg-info
python setup.py sdist bdist_wheel --universal
# Check the source and upload to the test repository
twine check dist/*
twine upload --repository-url https://test.pypi.org/legacy/ dist/*
# Go to https://test.pypi.org/project/proplot/ and make sure everything looks ok
# Then make sure the package is installable
pip install --index-url https://test.pypi.org/simple/ proplot
# Register and push to pypi
twine upload dist/*