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.

Reporting Bugs

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, 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 different versions.

To install tox, use:

pip install tox

and to run the tests, inside the top level of the repository, run:


Adding Examples

Examples should be added in the examples folder.

Adding ipython/jupyter notebook examples

Please submit extra jupyter notebook examples of usage of odes. Example notebooks should go in ipython_examples, and add a short description to ipython_examples/

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 docs/requirements.txt.

The API docs are located in the apidocs directory, and the requirements for building it are in apidocs/requirements.txt.

Creating a New Release

There are five steps to creating a new odes release:

  1. Make a non-development version.
  2. Create a new release on GitHub.
  3. Publish the new release on Zenodo.
  4. Upload the new release to PyPI.
  5. Bump the version to the next development version.

The main docs should automatically build on readthedocs, and the API docs should be built by doctr. You should check that the docs have updated once you have make the release.

Making a non-development version

To make a non-development version, inside change DEV=True to DEV=False, and if needed, modify MAJOR, MINOR and MICRO to set the new release version. Then commit only these changes and push them to the main repository (bmcage/odes).

Creating a new release on GitHub

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.

Publishing the new release on Zenodo

Go to uploads in Zenodo, edit the uploaded new release, adding addition information as needed such as ORCID, save and hit the publish button. This will generate a DOI.

Uploading the new release to PyPI

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 end).

In the cleaned repository, run:

python 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 for more information about uploading to PyPI.

Bumping the version to the next development version

Modify MAJOR, MINOR and MICRO in to a later version (increasing MICRO by 1 is sufficient). Also in, change back to DEV=True. Finally, copy the DOI badge of of the latest release from Zenodo to the, and commit only these two files. You can now run git stash pop to retrieve what you were working on.