Skip to content

developers.md

Latest commit

 

History

History
168 lines (112 loc) · 5.88 KB

developers.md

File metadata and controls

168 lines (112 loc) · 5.88 KB

Developer Documentation

Environment Setup

This repository is entirely agnostic to how developers set up their development environments. There is a provided devcontainer configuration file and we suggest using a devcontainer to set up and isolate your development environment.

Installing Development Dependencies

Install development dependencies using `uv`` with all the extras groups:

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Load env vars and PATH settings
source $HOME/.local/bin/env

# Install all dependencies including optional extras
uv sync --all-extras

# Activate the virtual environment
source .venv/bin/activate

Note: uv is a fast, Rust-based Python package installer and resolver that is PEP-compliant and fully compatible with pip and PyPI.

Once the development dependencies are installed and the uv-generated .venv is activated, you can run

pre-commit install

# Linux / WSL (devcontainer)
sudo apt-get install -y libatomic1

to get pre-commit hooks to automatically run the linting and formatting checks for you before each commit.

Authentication with Github is required to push to the repository. We suggest using SSH key authentication.

Testing

Testing is run with pytest and the order is randomized by pytest-randomly. To run all tests, run

pytest tests

Building Documentation with Sphinx

Documentation is automatically built on ReadTheDocs in response to every PR and release, but you can also build it locally with:

# From docs directory
make html

# macOS
open build/html/index.html

# Linux / WSL (devcontainer)
sudo apt install wslu
wslview build/html/index.html

Making a Pull Request

Feel free to fork this repo and submit a PR!

  • If you are working on an issue, link your PR to that issue.
  • All feature PRs should be destined for the main branch (trunk-based development).
  • Reviews are required before merging and our automated tests must pass.
  • Please fill out the PR template that is populated when creating a PR in the GitHub interface.

Release Process

Releases are automatically created using a GitHub Actions workflow that responds to pushes of annotated git tags.

Versioning

Version numbers must be PEP440 strings: https://peps.python.org/pep-0440/

That is,

[N!]N(.N)*[{a|b|rc}N][.postN][.devN]

Major Minor Patch Meanings

  • Major: Breaking API change.
  • Minor: Non-breaking features.
  • Patch: Bugfixes.

Preparing for Release

  1. Create a release branch named according to the major and minor version to be released. This branch is the long lived branch that will contain the tagged commit for the release (and possible future patch releases). The naming convention is release/X.Y. We drop the patch version on release branches so we can make bugfixes there.

  2. Bump the version of the package to the version you are about to release by manually editing the version field in the [project] section of pyproject.toml.

  3. Update the version identifier in CITATION.cff and meta.yaml.

  4. Update changelog.md to ensure the release notes for the version to be published is at the top and revisit README.md to keep it up to date.

  5. Open a PR to merge the release branch into main. This informs the rest of the team how the release process is progressing as you polish the release branch. You may need to rebase the release branch onto any recent changes to main and resolve any conflicts on a regular basis.

  6. When you are satisfied that the release branch is ready, tag the latest commit on the release branch with the desired version X.Y.Z and push the tag upstream. This will kick off the automatic release process.

  7. Merge the release branch back into main via a PR. Resolve any conflicts normally. This ensures that all changes in the release are incorporated into main and subsequent version releases.

Automatic Release Process

We use GitHub Actions for automatic release process that responds to pushes of git tags. When a tag matching a semantic version ([0-9]+.[0-9]+.[0-9]+* or test-release/[0-9]+.[0-9]+.[0-9]+*) is pushed, the release workflow runs as follows:

  1. Build distribution artifacts for PyPI.
  2. Push the PyPI distribution artifacts to PyPI. Pushes to TestPyPI if tag starts with test-release.
  3. Build and push the Anaconda distribution to the lasp Anaconda channel. Pushes with a test-release label if tag starts with test-release, otherwise labels as main.
  4. Create a GitHub Release that includes auto-generated release notes and the source code.

Official Releases

Official releases are published to the public PyPI (even if they are release candidates like 1.2.3rc1). This differs from test releases, which are only published to TestPyPI and are not published to GitHub at all. If the semantic version has any suffixes (e.g. rc1), the release will be marked as a prerelease in GitHub and PyPI.

To trigger an official release, push a tag referencing the commit you want to release.

git checkout release/X.Y
git pull
git tag -a X.Y.Z -m "Version X.Y.Z"
git push origin X.Y.Z

Test Releases

Test releases are published to TestPyPI only and are not published on GitHub. Test releases are triggered by tags prefixed with test-release.

To publish a test release, prefix the tag with test-release. This will prevent any publishing to the public PyPI and will prevent the artifacts being published on GitHub.

git checkout release/X.Y
git pull
git tag -a test-release/X.Y.Zrc1 -m "Test Release Candidate X.Y.Zrc1"
git push origin test-release/X.Y.Zrc1

Prereleases

Unless the pushed tag matches the regex ^[0-9]*\.[0-9]*\.[0-9]*, the release will be marked as a prerelease in GitHub. This allows "official" prereleases of suffixed tags.

Release Notes Generation

Release notes are generated based on commit messages since the latest non-prerelease Release.