# Contributing

## Local workflow

1. Create a virtual environment.
2. Install the package in editable mode with dev dependencies.
3. Run `pytest tests -q`.
4. Run `ruff check .`, `ruff format --check .`, and `mypy swarm` before publishing changes.

## Packaging

Package versions are derived from Git tags via the build configuration.
Tag and release automation run after successful CI on `main`.

## PyPI publishing

PyPI publishing uses Trusted Publishing from GitHub Actions. Before the first real release, configure the `swarm-agents` project on PyPI with this publisher:

1. Owner: `logarith-ms`
2. Repository: `swarm-agents`
3. Workflow: `.github/workflows/publish-pypi.yml`
4. Environment: `pypi`

After that, every pushed `v*` tag can publish without storing a PyPI API token in GitHub secrets.

## Commit conventions

Tag automation on `main` follows conventional commit semantics:

1. `feat:` -> minor bump
2. `fix:` or `perf:` -> patch bump
3. `!` or `BREAKING CHANGE:` -> major bump

Other commit types (`docs:`, `chore:`, `test:`, `style:`, `refactor:` without breaking change) do not create a release tag.

GitHub Releases are created from pushed `v*` tags and include generated release notes plus built artifacts.
PyPI publishing runs from the same tag event after the build succeeds.
