Skip to content

Developer Notes

This page contains essential information for developers contributing to or maintaining the ada-verona package.

Local installation for e.g. development purposes

If you want to install ada-verona locally using git:

git clone https://github.com/ADA-research/VERONA.git
cd VERONA
uv pip install -e .
uv pip install -e .[dev]  # to include development dependencies

Pre-Commit Hooks

We use pre-commit to automatically enforce code quality standards and consistency before commits.

Pre-commit is included in the dev dependencies. After installing the dev environment, set up the git hooks:

pre-commit install

This command hooks into your Git workflow and runs configured checks on staged files before each commit.

Skipping Specific Hooks

To skip a specific hook for a single commit, use the SKIP environment variable, e.g.:

SKIP=check-pyproject-requirements-sync git commit -m "Your message"

Opening a PR

Before opening a PR, please do the following steps:

  • Check you implementation and all the files you changed for the PR
  • Execute the tests python -m pytest --cov tests/ --verbose and check everything is passing
  • Create a new branch and upload you changes to GitHub
  • Open your PR, check that all workflows are passing and document your changes by describing:
    • What is the purpose of the PR and what issue is addressed.
    • What exactly was changed in this PR.
    • How did you test the changes.
  • After you documented the PR and checked that the workflows are passing assign a reviewer to the PR

Testing the documentation

  • Check the documentation locally using mkdocs serve

Package Release Steps

Prerequisites

Ensure you have the necessary permissions and setup for PyPI releases:

1. Bump Version Locally

Use uv to automatically update the version in pyproject.toml and uv.lock:

# For patch version (1.0.0 → 1.0.1)
uv version --bump patch

# For minor version (1.0.0 → 1.1.0)
uv version --bump minor

# For major version (1.0.0 → 2.0.0)
uv version --bump major

The package version is automatically resolved at runtime via importlib.metadata.version("ada-verona").

2. Commit Version Changes

git add pyproject.toml uv.lock
git commit -m "Bump version to 1.0.0-alpha.10"

3. Create and Push Git Tag

Important: Use the v prefix for the git tag, as this triggers the release workflow.

# Create tag matching the version
git tag v1.0.0

# Push commit and tag together
git push origin main
git push origin v1.0.0

4. Review and Approve Workflow

The release workflow requires approval from at least one council member (see governance.md) before deployment. Monitor the GitHub Actions page for the workflow run and approve it as needed.