CONTRIBUTING.rst

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.