Contributing¶
Style guide¶
We follow PEP8 standards with the following exceptions:
- Use tabs instead of spaces - this allows all individuals to have visual depth of indentation they prefer, without changing the source code at all, and it is simply smaller
Testing¶
Easiest way to run tests is by running the command tox
from the terminal. The default Python environments for testing with are py27 and py34, but you can specify your own by running e.g. tox -e py35
.
Branching / Release¶
We currently use the gitflow workflow. Feature branches are created from
and merged back to the master
branch. Please always make a Pull Request
when you contribute.
See also the much simpler github flow here
Release¶
To make a release and deploy to PyPI, please follow these steps (we highly suggest to leave the realse to admins of ExpAn):
- assuming you have a master branch that is up to date, create a pull request from your feature branch to master (a travis job will be started for the pull request)
- once the pull request is approved, merge it (another travis job will be started because a push to master happened)
- checkout master
- create a new tag
- run documentation generation which includes creation of changelog
- push tags to master (a third travis job will be started, but this time it will also push to PyPI because tags were pushed)
The flow would then look like follows:
bumpversion (patch|minor)
make docs
git add CHANGELOG.*
git commit -m "update changelog"
git push
git push --tags
You can then check if the triggered Travis CI job is tagged (the name should be eg. ‘v1.2.3’ instead of ‘master’).
Note that it has a flaw that changelog generator will not put the changes of the current release, because it reads the commit messages from git remote.
ToDo: One solution could be to discard the automatic changelog generator and manually write the changelog before step 1, and then config make docs to use this changelog file.
We explain the individual steps below.
Versioning¶
For the sake of reproducibility, always be sure to work with a release when doing the analysis!. We use semantic versioning (http://semver.org).
The version is maintained in setup.cfg
, and propagated from there to various files
by the bumpversion
program. The most important propagation destination is
in version.py
where it is held in the string __version__
with
the form:
'{major}.{minor}.{patch}'
Bumping Version¶
We use bumpversion to maintain the __version__
in version.py
:
$ bumpversion patch
or
$ bumpversion minor
This will update the version number, create a new tag in git, and commit the changes with a standard commit message.
Travis CI¶
We use Travis CI for testing builds and deploying our PyPI package.
A build and test is triggered when either
- a commit is pushed to master
- or a pull request to **master is opened.
A release to PyPI will be triggered if a new tag is pushed to master.
If you wish to skip triggering a CI task (for example when you change documentation), please include [ci skip]
in your commit message.