Reporting Bugs, Contributing and Releasing¶
We welcome contributions, whether as bug reports, improvements to the code, or more examples.
Please note that all contributions are subject to our code of conduct.
odes bug tracker is on GitHub.
When reporting bugs, please include the versions of Python,
odes and SUNDIALS,
as well as which OS this appears on.
Getting the code¶
The primary repository is at https://github.com/bmcage/odes, and it is the repository that pull requests should be made against.
Work should be done in a private branch based on master, with pull requests made against master.
Running the Tests¶
odes uses tox to manage testing across
To install tox, use:
pip install tox
and to run the tests, inside the top level of the repository, run:
Examples should be added in the
Adding ipython/jupyter notebook examples¶
Please submit extra jupyter notebook examples of usage of
notebooks should go in
ipython_examples, and add a short description to
Building the Docs¶
The documentation for
odes is split into two parts, the main docs (of which
this is a part), and the API docs. Both the main docs and API docs use sphinx
to build the docs, and running
make html inside either of the associated
directories will cause sphinx to create a html version of the docs.
The main docs are located in the
docs directory, and the requirements for
building it are in
The API docs are located in the
apidocs directory, and the requirements for
building it are in
Creating a New Release¶
There are five steps to creating a new
- Make a non-development version.
- Create a new release on GitHub.
- Publish the new release on Zenodo.
- Upload the new release to PyPI.
- Bump the version to the next development version.
Making a non-development version¶
To make a non-development version, inside
DEV=False, and if needed, modify
MICRO to set the new release version.
Then commit only these changes and push them to the main repository (bmcage/odes).
On GitHub, draft a new release by clicking the appropriate button. Use the version number from the non-development commit as the title, and hit release. This will upload the release for a DOI to Zenodo as draft.
Make sure the current checkout is the non-development commit. To make sure no additional changes are included in the release, run:
git stash save --no-keep-index --all
This saves the current working directory, then cleans it. The changes can be
retrieved by running
git stash pop (but you should not do this until the
In the cleaned repository, run:
python setup.py sdist --formats=gztar
which creates a
dist directory containing a
tar.gz file, the sdist for
the release. To upload the sdist to PyPI, run:
twine upload dist/*
See https://packaging.python.org/tutorials/distributing-packages/#uploading-your-project-to-pypi for more information about uploading to PyPI.
Bumping the version to the next development version¶
common.py to a later version (increasing
MICRO by 1 is sufficient). Also in
common.py, change back to
DEV=True. Finally, copy the DOI badge of of the latest release from Zenodo to the
README.md, and commit only these two files. You can now run
git stash pop to retrieve what you were working on.