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.

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 pdm-bump docs for the list of available bump rules.

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 pdm-bump'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 etc.) then hit 'Publish release'. This triggers a release to PyPI (which you can then add to the release if you want).

  3. Go to your conda feedstock repository (likely something like https://github.com/conda-forge/elicito-feedstock) and make a new merge request that updates your recipe/meta.yaml file to point to the newly released version on PyPI.

  4. If you have updated any dependencies, copy these across to your recipe/meta.yaml file.

  5. If you are releasing a locked version on conda too, you can generate the pins for your lock file with scripts/print-conda-recipe-pins.py.

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

  7. Enjoy the newly available version

Further details#

We use pdm for building our project, while uv figures out how it wants to support building. This gives us the added benefit that we can use pdm-build-locked to build locked versions of our package. It is for these reasons that we create a pdm.lock file 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 elicito.readthedocs.io.