Contributions are highly welcomed and appreciated. Every little bit helps, so please do not hesitate! 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 with the label “feature.” 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!
Bugs should be reported in the issue tracker with the label “bug”. When reporting a bug, please include:
Your operating system name and version, your python version, and your proplot and matplotlib versions.
If the bug also involves cartopy or basemap, please include these versions as well.
An example that can be copied and pasted to reproduce the bug.
If you can figure out how to fix the bug, feel free to submit a pull request.
Many packages include
.py scripts in a
and have the Travis Continuous Integration service
automatically run them. Currently, we do
not use the
tests folder – we just have Travis run the
examples in the
docs folder (see
However, this is a major 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.
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
.ipynbnotebook files in the
docsfolder. The notebooks are embedded in the User Guide using nbsphinx.
The default ReST role is
py:obj. Please include
py:objlinks whenever discussing particular functions or classes – for example, if you are discussing the
formatmethod, please write
format. ProPlot also uses intersphinx so you can link to external packages like matplotlib and cartopy.
When editing the
.ipynbnotebook files, make sure to put your example descriptions inside reStructedText cells, not markdown cells. This lets us add sphinx directives and API links to the descriptions. See this guide for how to convert cells to ReST.
To build the documentation locally, use the following commands:
cd docs conda env update -f environment.yml make html
The built documentation should be available in
Preparing 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:
git clone firstname.lastname@example.org:YOUR_GITHUB_USERNAME/proplot.git cd proplot git remote add upstream email@example.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 when you
import proplot, the local copy is used, rather than the stable version you downloaded from PyPi. You can print
proplot.__file__to verify the correct version has been imported.
Install pre-commit and its hook on the
pip install --user pre-commit pre-commit install
pre-commitwill run whenever you commit. https://pre-commit.com/ is a framework for managing and maintaining multi-language pre-commit hooks to ensure code-style and code formatting is consistent.
If you intend to make changes or add examples to the ipython notebooks, you need to install and configure nbstripout:
pip install --user nbstripout git config --local include.path ../.gitconfig
This adds the
proplot/.gitconfigfile (which is not recognized by git) to the local
proplot/.git/configconfiguration file, which defines the filters declared in
proplot/.gitattributes. It is necessary because git cannot sync repository-specific configuration files.
After this is done, cell output will be “invisible” to git; the version control system only ever “sees” the content written in each cell. This makes
git diffs much more legible, significantly reduces the repo size, and lets us test notebook examples using nbsphinx.
You can now edit your local working copy as necessary. Please follow the PEP-8 style guide. When committing,
nbstripoutwill ignore changes to notebook cell output and
pre-commitwill 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”.
Create a new changelog entry in
CHANGELOG.rst. The entry should be entered as:
<description> (:pr:`<PR number>`) `<author name>`_
<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.rstif 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
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 while you’re working on this. The PR will update as you add more commits. ProPlot developers and contributors can then review your code and offer suggestions.
ProPlot follows semantic versioning, e.g.
vX.Y.Z. A major version (
X) causes incompatible
API changes, a minor version (
Y) adds functionality, and a patch (
Z) covers bug fixes.
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.Zwith 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
After all tests pass and the pull request has been approved, merge into
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/*