Contributing¶
We welcome contributions to multidms <multidms>! This document describes how to edit the package, run the tests, build the docs, put tagged versions on PyPI, etc.
Editing the project¶
Package structure¶
Package code is in multidms
Docs are in docs
Jupyter notebooks are in notebooks
Unit tests are in tests
Modify the code via pull requests¶
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
In general, We recommend following the same instructions as tskit for pull requests.
Documentation¶
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.
For more elaborate functionality, put unit tests in tests.
Formatting¶
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 actions tests will not pass unless the files have been formatted. Note that this will change files/notebooks that you may be actively editing.
Adding dependencies¶
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 in the “dependencies” section of the pyproject.toml file.
Testing¶
Adding tests¶
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
Running the tests locally¶
After you make changes, you should run two sets of tests. To run the tests, go to the top-level packag directory - making sure to install and activate a development environment.
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 --doctest-modules -vv
If you need to change the pytest configuration, edit the pytest.ini file.
Automated testing using github actions¶
The aforementioned black, ruff and pytest tests will be run automatically by the github actions continuous integration (CI) system once a pull request is submitted.
Building documentation¶
See docs/README.rst for information on how to build the documentation.
Tagging versions and putting on PyPI¶
When you have a new stable release that has been commited and pushed to the main branch, you will want to tag it and put it on PyPI where it can be installed with pip.We recommend making use of the bumpver package to do this - as the pyproject.toml is setup to automatically fetch the latest version and update all the version numbers in the code/docs.
With a clean working tree, simply
bumpver update --patch
Which will commit, and tag the new version. Note version format is MAJOR.MINOR.PATCH, for major and minor version changes use the –major or –minor flags, respectively.
Next, push the new tag to the remote repository
git push --tags origin main
This will trigger the action to build and upload the package to the test PyPI repository.
To publish to the real PyPI, you simply use the github web interface to pin a new release on the tag you just created. This will trigger the publish package action to build and upload the package to the real PyPI repository.