diff --git a/README.md b/README.md index ba2b476..49afc0d 100644 --- a/README.md +++ b/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:`. -`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). diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000..c3ae0d9 --- /dev/null +++ b/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.