Move the release process to RELEASING.md

README.md

@@ -56,6 +56,10 @@ docker run -d --name ktms-admin -p 8080:8080 \
   coyl/ktms-admin:latest
 ```
 
+Pin a release with `coyl/ktms-admin:X.Y.Z`; `X.Y` follows the newest release of its line and `latest`
+the newest of all. Images are signed ([SECURITY.md](SECURITY.md)); the old name `coyl/llm-proxy-admin`
+gets no releases after 0.4.0.
+
 Open `PUBLIC_URL`, sign in with that e-mail and password, and you are in.
 [`examples/compose.yaml`](examples/compose.yaml) starts the whole family (KTMS, light-tokenmeter and
 this console on one Postgres) with the first-run steps in its header.
@@ -373,18 +377,5 @@ Layout: `cmd/ktms-admin` (entrypoint), `internal/auth` (sessions, allowlists, si
 `internal/api` (JSON API and guards), `internal/usage` (light-tokenmeter client and the greedy/worthy
 analysis), `internal/config`, `internal/web` (embedded UI).
 
-### Releasing
-
-Pushing a `vX.Y.Z` tag publishes a multi-arch image to Docker Hub as `coyl/ktms-admin:<version>`.
-`latest` moves only with the newest stable release. The old name `coyl/llm-proxy-admin` gets no new
-releases after 0.4.0. The
-image is signed with keyless cosign and carries an SBOM and provenance (verify like the gateway's
-images, see [KTMS SECURITY.md](https://github.com/ai-process/ktms/blob/main/SECURITY.md#verifying-a-release),
-with `docker-publish.yml` of `ai-process/ktms-admin`). The repository needs the secrets
-`DOCKER_USERNAME` and `DOCKER_PASSWORD`.
-
-```bash
-git tag v1.0.0 && git push origin v1.0.0
-```
-
-Contributions are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md). Licensed under the [Apache License 2.0](LICENSE).
+Contributions are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md); maintainers release as described in
+[RELEASING.md](RELEASING.md). Licensed under the [Apache License 2.0](LICENSE).

RELEASING.md

@@ -0,0 +1,43 @@
+# Releasing ktms-admin
+
+For maintainers. The console shares its major version with KTMS (see
+[Compatibility](README.md#compatibility)): a fix is a patch, a feature is a minor, renaming or
+dropping a setting waits for a new major.
+
+## Steps
+
+1. In a pull request (`chore(release): X.Y.Z`):
+   - move the `[Unreleased]` entries of [`CHANGELOG.md`](CHANGELOG.md) under
+     `## [X.Y.Z] - YYYY-MM-DD`;
+   - when the release needs a newer KTMS or light-tokenmeter, move the pair in
+     [`scripts/e2e.refs`](scripts/e2e.refs) to their release tags, copy KTMS's `proto/ktms/v1` at
+     that tag over `proto/ktms/v1`, run `make proto`, and update the table in
+     [Compatibility](README.md#compatibility);
+   - set `V=` in [`SECURITY.md`](SECURITY.md) to the new tag.
+2. After it is merged, tag main, push the tag, and publish the GitHub Release with the
+   changelog section as its notes:
+
+   ```bash
+   git tag vX.Y.Z && git push origin vX.Y.Z
+   gh release create vX.Y.Z --title "ktms-admin X.Y.Z" --notes-file notes.md --verify-tag
+   ```
+
+## What the tag publishes
+
+[`docker-publish.yml`](.github/workflows/docker-publish.yml): the signed multi-arch image
+`coyl/ktms-admin:X.Y.Z` with an SBOM and provenance. `X.Y` moves only for the newest release of
+its line and `latest` only for the newest of all, so a backport moves neither. The old name
+`coyl/llm-proxy-admin` gets no releases after 0.4.0.
+
+## Secrets
+
+`DOCKER_USERNAME` and `DOCKER_PASSWORD` (an access token) for Docker Hub. Signing needs no
+secret: cosign signs keylessly with the workflow's OIDC identity, which
+[`SECURITY.md`](SECURITY.md) pins.
+
+## Checks
+
+Every pull request runs `scripts/proto-check.sh` (the proto copy equals KTMS's at the ref in
+`scripts/e2e.refs`) and `scripts/e2e.sh` against that KTMS and light-tokenmeter pair;
+[`e2e-main.yml`](.github/workflows/e2e-main.yml) runs the e2e test daily against their `main`, so
+a break shows up before the pair is moved.