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:
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¶
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.