Skip to content

Development#

Notes for developers. If you want to get involved, please do! We welcome all kinds of contributions, for example:

  • docs fixes/clarifications
  • bug reports
  • bug fixes
  • feature requests
  • pull requests
  • tutorials

Workflows#

We don't mind whether you use a branching or forking workflow. However, please only push to your own branches. Pushing to other people's branches is best avoided because it is a recipe for disaster and is never required in our experience.

Try and keep your merge requests as small as possible (focus on one thing if you can). This makes life much easier for reviewers which allows contributions to be accepted at a faster rate.

Using uv with a compiled package#

Using uv with a compiled package is a bit more painful. Whenever you do uv run or uv sync or similar, uv tries to install the compiled package as an editable package. This can then cause issues on later calls to uv run or uv sync as having compiled packages as editable packages doesn't really work (you get errors like ImportError: re-building the <package-name> meson-python editable wheel package failed). The way around this is to:

  1. use the --no-editable flag with uv sync so that uv doesn't do an editable install
  2. use the --no-sync flag with uv run (and any other command that takes this flag) so that uv doesn't try and re-build packages
  3. use the --reinstall-package flag with uv run whenever you want to be sure that the latest changes will be used for running a command (yes, this makes running things slower, but slower and reliable is better than broken)

We include these flags in our Makefile and GitHub workflows if you want to see them in use.

If you forget and run uv run ... in your terminal. The easiest solution seems to be to delete your virtual environment entirely and start again. We haven't found a way to get out of an accidental editable install.

Language#

We use British English for our development. We do this for consistency with the broader work context of our lead developers.

Versioning#

This package follows the version format described in PEP440 and Semantic Versioning to describe how the version should change depending on the updates to the code base.

Releasing#

Releasing is semi-automated via a CI job. The CI job requires the type of version bump that will be performed to be manually specified. See the uv version docs (specifically the --bump flag) for the list of available bump rules.

Releasing also includes building of wheels for major operating systems and supported Python versions. This is done thanks to cibuildwheel, an incredible service. The wheel building can be quite tricky and fiddly. If there are issues, we recommend starting with the cibuildwheel docs or raising an issue to discuss with the other maintainers.

Standard process#

The steps required are the following:

  1. Bump the version: manually trigger the "bump" workflow from the main branch (see here: bump workflow). A valid "bump_rule" (see uv's docs) will need to be specified. This will then trigger a draft release.

  2. Edit the draft release which has been created (see here: project releases). Once you are happy with the release (removed placeholders, added key announcements, checked that all the expected wheels and source distribution is there etc.) then hit 'Publish release'. This triggers a release to PyPI (which you can then add to the release if you want).

  3. That's it, release done, make noise on social media of choice, do whatever else

  4. Enjoy the newly available version [TODO: add in conda release instructions]

Further details#

We use uv's build backend for building our project and scripts/add-locked-targets-to-pyproject-toml.py to provide locked extra groups for our package. Including locked extra groups is why we run scripts/add-locked-targets-to-pyproject-toml.py before any step related to building the package in the CI.

Read the Docs#

Our documentation is hosted by Read the Docs (RtD), a service for which we are very grateful. The RtD configuration can be found in the .readthedocs.yaml file in the root of this repository. The docs are automatically deployed at example-fgen-basic.readthedocs.io.