This document describes how to edit the package, run the tests, build the docs, put tagged versions on PyPI, etc.
- Package code is in binarymap
- 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 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.
The Jupyter notebooks in notebooks can be run interactively on mybinder by going to the following link: https://mybinder.org/v2/gh/jbloomlab/binarymap/main?filepath=notebooks
In order for this to work, you need to keep the environment.yml configuration file up to date with the dependencies for running these notebooks as described here. Note that unlike for the install_requires in setup.py, you may want to pin exact versions here to get reproducible installations. Look into the pip freeze and conda env export commands on how to automatically create such a configuration file.
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 .
Then run the tests with pytest by running:
pytest
If you need to change the pytest configuration, edit the pytest.ini file.
The aforementioned tests are run automatically by Github actions as specified in .github/workflows/test.yml.
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.