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

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:

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.