Contributing to pycurious

We welcome contributions to pycurious, large or small *. That can be in the form of new code, improvements to the documentation, helping with a missing test, or it may even just be pointing out a bug or potential improvement to the team.

For bugs and suggestions, the most effective way to reach the team is by raising an issue on the github issue tracker. Github allows you to classify your issues so that we know if it is a bug report, feature request or feedback to the authors.

If you wish to contribute some changes to the code then you should submit a pull request. On github we can review the code that you are contributing and discuss it before the changes are merged into the development version of the code. Before embarking on changes to the code, please first check the open issues and pull requests: we may have been working on something similar already.

How to create a Pull Request (PR)

Create your own fork of the project on GitHub: log into your GitHub account, navigate to the pycurious repository and click on the fork button at the top right corner of this repository. You can find detailed instructions and a discussion of how to fork a repository, clone it locally and work on the changes in the GitHub guides.

When to make your pull request

It is much easier to merge in small changes to the code than extensive ones that touch multiple files. If a small incremental change is possible, please issue a request for that change rather than saving everything up.

It is a good idea to commit frequently and with commit messages that refer to the changes that have been make and why they have been made. The commit message is usually browsed without seeing the actual changes themselves and which sections of the code have been altered so a helpful message provides relevant details.

We want your help!

We welcome all contributions to pycurious, but if you would like to assist us on our development milestones, then we would appreciate all pull requests pertaining to the following areas:

  • Implementing different taper functions in addition to built-in numpy functions (e.g. numpy.hanning, numpy.hanning)

  • Enhancing I/O capabilities (e.g. exporting to netCDF, HDF5 formats)

  • Expanding the Jupyter notebook examples for specific use cases and study areas.

Tests

We use pytest for the unit testing framework in pycurious. Install the test extra and run the suite from the source directory:

python -m pip install -e ".[test]"
pytest                # the full suite
pytest -m "not slow"  # skip the calibration tests that fit hundreds of realisations

The existing tests should be passing before you start coding (help us out with an issue if that is not the case !) and when you have finished. Any new functionality should also have tests that we can use to verify the code. It is important that you make it clear if the original tests have had to change to accomodate new code / functionality.

* Small changes are our favorites as they are much easier to quickly merge into the existing code. Proofreading typos, bug fixes, … the little stuff is especially welcome.

Building the documentation

The documentation is built with Sphinx using the Furo theme, with MyST-NB rendering both the Markdown pages and the tutorial notebooks. To build it locally:

python3 -m pip install -e ".[docs,examples,mapping]"
python3 docs/copy_notebooks.py            # stage notebooks into docs/tutorials/
sphinx-build -b html docs docs/_build/html

Open docs/_build/html/index.html. The self-contained tutorials (Ex1–Ex4 for both methods) execute at build time; the two Ex5 notebooks each need ~600 MB of external data and render as code only.

Releasing (maintainers)

Continuous integration runs on GitHub Actions:

  • tests.yml — runs the test suite on every push and pull request across Python 3.9–3.13.

  • docs.yml — builds these docs on every push and pull request, and deploys them to GitHub Pages from master.

  • publish.yml — builds the sdist and wheel and publishes them to PyPI when a GitHub release is published.

A release is cut by publishing a GitHub release for the tagged version; the publish.yml workflow then uploads to PyPI automatically. Two settings are configured once on the repository:

  • GitHub Pages — Settings → Pages → Source set to GitHub Actions, so docs.yml can deploy to https://brmather.github.io/pycurious/.

  • PyPI Trusted Publishing — on the pycurious project at PyPI, add a trusted publisher pointing at owner brmather, repository pycurious, workflow publish.yml, environment pypi. This lets Actions publish over OIDC with no stored password or API token.