configcenter/docs/release-policy.md

Release Policy

Version source of truth

Config Center uses Semantic Versioning. A production release is created only from an annotated or lightweight Git tag named vMAJOR.MINOR.PATCH, for example v0.2.0.

Before creating the tag, move the relevant entries from CHANGELOG.md Unreleased into a dated heading in the form ## [MAJOR.MINOR.PATCH] - YYYY-MM-DD. The release workflow rejects a tag that has no matching changelog heading.

Server images expose the release version, Git commit, and build timestamp through OCI labels and the configcenter -version command. Production deployments must reference immutable image digests rather than mutable tags.

Required release gates

A release is eligible only when all repository verification succeeds:

1. protobuf generation has no drift;
2. Go unit/integration tests and race tests pass;
3. golangci-lint and govulncheck pass;
4. Python SDK compile validation and Web Console production build pass;
5. YAML, Docker Compose, and migration policy validation pass;
6. dependency and final container image scans contain no untreated HIGH or CRITICAL vulnerabilities.

The tag-triggered workflow then builds Linux amd64 and arm64 server/web images, pushes them to GHCR, generates SPDX JSON SBOMs, and signs each immutable digest with Cosign using GitHub OIDC. The workflow verifies the signature immediately after signing.

Database migration rules

PostgreSQL migrations under internal/store/postgres/migrations are append-only and use contiguous filenames such as 004_add_feature.sql.

• Never edit, rename, reorder, or delete a migration that may have been applied outside a developer's disposable database.
• Schema changes must be forward-compatible with the previous application release during rolling deployment.
• Destructive changes use expand/migrate/contract: add the new structure first, migrate traffic/data, and remove the old structure only in a later release.
• The application runtime verifies migration checksums and refuses to start if an already-recorded migration has changed.

Rollback admission

Application rollback is permitted only when the database schema currently deployed remains compatible with the target application version. If a release contains a migration that breaks backward compatibility, rollback is blocked until a corrective forward migration restores compatibility.

Database rollback is not implemented by executing down migrations in production. Recovery from an erroneous destructive migration uses a tested PostgreSQL backup/restore procedure or a new forward migration, depending on incident scope.

Release procedure

1. Ensure the main branch is green and update CHANGELOG.md.
2. Run make verify locally where practical.
3. Create and push vMAJOR.MINOR.PATCH.
4. Wait for the Release workflow to finish successfully.
5. Record the server and web image digests and deploy by digest to staging.
6. Complete staging smoke/load/fault checks and production change approval.
7. Promote the exact tested digests to production; do not rebuild between staging and production.

The remaining staging mTLS, backup/restore, sustained load, and fault-injection gates are tracked separately because they require a real multi-node environment.