# 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:

```bash
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](https://pre-commit.com/) 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:

```bash
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.:

```bash
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:

- You must be a member of the [PyPI ada-verona project](https://pypi.org/project/ada-verona/) with release authority
- Configure [trusted publishing](https://docs.pypi.org/trusted-publishers/) with your credentials on PyPI

### 1. Bump Version Locally

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

```bash
# 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

```bash
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.

```bash
# 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](../governance.md)) before deployment. Monitor the [GitHub Actions](https://github.com/ADA-research/VERONA/actions) page for the workflow run and approve it as needed.




