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

To install tox, use:

pip install tox

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

tox

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/README.md.

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:

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.

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. If docs are not updated automatically, login to readthedocs go to scikits, builds, and build latest and master manually.

Making a non-development version¶

To make a non-development version, inside common.py 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 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:

python3 -m pip install --user --upgrade twine
python3 -m twine upload --repository-url https://upload.pypi.org/legacy/ 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¶

Modify MAJOR, MINOR and MICRO in 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.

Build documentation on ReadTheDocs¶

Login on readthedocs, as release manager you should have access to project scikits-odes. Update the build documentation: latest, new release, master. On new bugfix point release, deactivate the previous point release docs.