This document describes how to edit the package, run the tests, build the docs, put tagged versions on PyPI, etc.
- Package code is in polyclonal
- Docs are in docs
- Jupyter notebooks are in notebooks
- Unit tests are in tests
To make changes to the code, you should make a branch or fork, make your changes, and then submit a pull request. If you aren't sure about pull requests:
- A general description of pull requests: https://help.github.com/en/articles/about-pull-requests
- How to create a pull request: https://help.github.com/en/articles/creating-a-pull-request
- How to structure your pull requests (one conceptually distinct change per pull request): https://medium.com/@fagnerbrack/one-pull-request-one-concern-e84a27dfe9f1
You should document your code clearly with numpy style documentation. You may also want to write sphinx documentation / examples in docs or the notebooks to demonstrate large-scale functionality.
You should add tests. For simple things, these can be doctests in the code. For more elaborate functionality, put unit tests in tests. Note also that the Jupyter notebooks in notebooks are tested via nbval. If you are getting errors on these notebook tests due to testing cells that output objects that can't be properly tested (such as widgets), see the nbval-ignore-output tag option discussed in the nbval docs.
The code is formatted using Black, which you can install using pip install "black[jupyter]". You may also wish to install a Black extension in your editor to, for example, auto-format upon save. In any case, please run Black using black . before submitting your PR, because the tests will not pass unless the files have been formatted. Note that this will change files/notebooks that you may be actively editing.
The version is single sourced in __init__.py. See here for more information on version numbers.
Conceptual descriptions of changes should also be tracked in the CHANGELOG.
When you add code that uses a new package that is not in the standard python library, you should add it to the dependencies specified under the install_requires option in setup.py. See here for information on how to do this, and how to specify minimal required versions. As described in the above link, you should not pin exact versions in install_requires in setup.py unless absolutely necessary.
As you add new codes, you should create tests to make sure it is working correctly. These can include:
- doctests in the code
- unit tests in the ./tests/ subdirectory
After you make changes, you should run two sets of tests. To run the tests, go to the top-level packag directory. Then make sure that you have installed the packages listed in test_requirements.txt. If these are not installed, install them with:
pip install -r test_requirements.txt
Then use ruff to lint the code by running:
ruff check .
If you need to change the ruff configuration, edit the ruff.toml file.
Then run the tests with pytest by running:
pytest
If you need to change the pytest configuration, edit the pytest.ini file.
The aforementioned ruff and pytest tests will be run automatically by the continuous integration system as specified in the GitHub Actions file [.github/workflows/test.yaml](.github/workflows/test.yaml).
See docs/README.rst for information on how to build the documentation.
When you have a new stable release, you will want to tag it and put it on PyPI where it can be installed with pip. First, make sure the version number is up-to-date in __init__.py and the CHANGELOG. Then commit the code to GitHub if you haven't already done so. Next tag the version, as in:
git tag -a 0.1.0 -m 'version 0.1.0'
and then push the tag to GitHub with:
git push --tags
Finally, upload to PyPI with twine as described here. Note that this requires you to have registered the package on PyPI if this is the first version of the package there.