How to contribute to this package¶
This document describes how to edit the package, run the tests, build the docs, put tagged versions on PyPI, etc.
Editing the project¶
Developpment environnement¶
We’re using conda environment to install all dependencies needed for Museo ToolBox developpement.
conda env create -f .environment.yml
This will create an environnement called museotoolbox-dev
, to activate it, just type :
conda active museotoolbox-dev
Package structure¶
Package code is in museotoolbox folder.
Docs can be generated by typing
Make doc
at the root of folder.Unit tests are in test folder.
Modify the code via pull requests¶
To make changes to the code, you should make a branch or fork, make your changes, and then submit a pull request. If you aren’t sure about pull requests:
A general description of pull requests: https://help.github.com/en/articles/about-pull-requests
How to create a pull request: https://help.github.com/en/articles/creating-a-pull-request
How to structure your pull requests (one conceptually distinct change per pull request): https://medium.com/@fagnerbrack/one-pull-request-one-concern-e84a27dfe9f1
Tests and documentation¶
You should document your code clearly with numpy style documentation. You should add tests. For simple things, these can be doctests in the code. For more elaborate functionality, put unit tests in test.
Versions and CHANGELOG¶
The version is single sourced in __init__.py.
When modifying a tagged version (e.g., 0.1.0
), indicate you are working on a development version by adding a dev
(e.g., 0.1.dev1
).
See here for more information on version numbers.
Conceptual descriptions of changes should also be tracked in the CHANGELOG.
Adding dependencies¶
When you add code that uses a new package that is not in the standard python library, you should add it to the dependencies specified under the install_requires
option in setup.py.
See here for information on how to do this, and how to specify minimal required versions.
As described in the above link, you should not pin exact versions in install_requires
in setup.py unless absolutely necessary.
Testing¶
Adding tests¶
As you add new codes, you should create tests to make sure it is working correctly. These can include:
doctests in the code
unit tests in the ./test/ subdirectory
Running the tests locally¶
After you make changes, you should run two sets of tests. To run the tests, go to the top-level package directory.
Then run the tests with pytest under the museotoolbox-dev
conda environnement by running :
make pytest
Building the documentation¶
The documentation will be built for each new commit in the master
branch.
However, you can build your own documentation in order by typing under the museotoolbox-dev
conda environnement :
make ddoc
Automated testing on Travis¶
The aforementioned pytest tests will be run automatically by the Travis continuous integration system as specified in the .travis.yml file. Note that running the Travis tests requires you to register the project with Travis.
If the tests are passing, you will see this on the Travis badge on GitHub repo main page.
Tagging versions and putting on PyPI¶
When you have a new stable release, you will want to tag it and put it on PyPI where it can be installed with pip. First, make sure the version number is up-to-date in __init__.py and the CHANGELOG. Then commit the code to GitHub if you haven’t already done so. Next tag the version, as in:
git tag -a 0.1.0 -m 'version 0.1.0'
and then push the tag to GitHub with:
git push --tags
Finally, with Travis, specify your pypi account in .travis.yml file to publish a new version on pypi when you publish a stable release on github.
Note that this requires you to have registered the package on PyPI if this is the first version of the package there.