docs: document conventional commits and the approval-gated release flow

Author: raederan

CONTRIBUTING.md

@@ -23,17 +23,32 @@ make install    # environment + pre-commit hooks
 covers details such as running the integration tests and serving the docs
 locally.
 
+## Commit messages
+
+Commits follow [Conventional Commits](https://www.conventionalcommits.org/):
+`type(scope): subject`, for example `fix: correct sidebar collapse on small
+screens`. The scope is optional. A local `commit-msg` hook (installed by
+`make install`) rejects malformed messages, because they drive the automated
+release below.
+
+| Type | Release effect |
+| ---- | -------------- |
+| `feat` | minor release |
+| `fix`, `perf` | patch release |
+| `BREAKING CHANGE:` footer, or `!` after the type | major release |
+| `docs`, `chore`, `test`, `refactor`, `ci`, `style`, `build` | no release |
+
 ## Releasing
 
-Releases are fully automated with
-[python-semantic-release](https://python-semantic-release.readthedocs.io/):
-every push to `main` is analyzed, and conventional commits decide the
-outcome. `fix:` commits trigger a patch release, `feat:` a minor release
-and a `BREAKING CHANGE:` footer (or `!` after the type) a major release;
-other types (`chore:`, `docs:`, `ci:`, ...) release nothing. CI then
-updates the changelog, tags, builds, publishes to PyPI via trusted
-publishing and deploys the versioned docs. No manual version bumping or
-tagging.
+There is no standing release branch: work goes `feature branch -> main`.
+Every pull request into `main` runs the checks, the integration suite, and a
+bot comment predicting the version a merge would release. Merging starts the
+release job, which pauses on the `pypi` GitHub environment for a required
+reviewer to approve; approve and
+[python-semantic-release](https://python-semantic-release.readthedocs.io/)
+bumps the version (in `pyproject.toml`, never edited by hand), updates the
+changelog, tags, builds, publishes to PyPI via trusted publishing and deploys
+the versioned docs. Reject the approval and nothing ships.
 
 ## AI Guidelines
 

docs/dev.md

@@ -22,6 +22,9 @@ Requires [uv](https://docs.astral.sh/uv/) and `git`.
     uv run pre-commit install
     ```
 
+`pre-commit install` wires both hook stages (`pre-commit` and `commit-msg`);
+the latter enforces the commit message format below.
+
 ## Quality checks
 
 Lock consistency, linting and formatting (pre-commit incl. ruff), static
@@ -137,17 +140,38 @@ strict build that fails on any warning:
     uv build
     ```
 
-## Releasing
+## Commit messages
+
+Commits follow [Conventional Commits](https://www.conventionalcommits.org/):
+`type(scope): subject`, scope optional. The local `commit-msg` hook (see
+Setup) rejects malformed messages, because they drive the automated release
+below.
 
-Releases are fully automated
-([python-semantic-release](https://python-semantic-release.readthedocs.io/)):
-conventional commits on `main` decide the version bump (`fix:` patch,
-`feat:` minor, `BREAKING CHANGE:`/`!` major), CI updates the changelog,
-tags `vX.Y.Z`, builds, publishes to PyPI via trusted publishing and
-deploys the versioned docs. The package version is derived from the tag
-by `hatch-vcs`; nothing is bumped manually.
+| Type | Release effect |
+| ---- | -------------- |
+| `feat` | minor release |
+| `fix`, `perf` | patch release |
+| `BREAKING CHANGE:` footer, or `!` after the type | major release |
+| `docs`, `chore`, `test`, `refactor`, `ci`, `style`, `build` | no release |
+
+## Releasing
 
-To preview what the next release would be:
+There is no standing release branch: work goes `feature branch -> main`
+directly. Every pull request into `main` runs `main.yml` (quality, tests,
+docs), the integration suite, and a `version-preview` job that comments the
+version a merge would release, computed with the same conventional commits.
+
+Merging to `main` starts the release job
+(`on-release-main.yml`), which pauses on the `pypi` GitHub environment for a
+required reviewer to approve -- this is the deliberate-release control, in
+place of a staging branch. Once approved,
+[python-semantic-release](https://python-semantic-release.readthedocs.io/)
+bumps the static version in `pyproject.toml` and `CITATION.cff` (never edited
+by hand), updates `CHANGELOG.md`, relocks `uv.lock`, commits, tags `vX.Y.Z`,
+builds, publishes to PyPI via trusted publishing and deploys the versioned
+docs. Reject the approval and nothing ships.
+
+To preview what the next release would be locally:
 
 ```bash
 uv run semantic-release --noop version