diff --git a/.gitea/scripts/validate-tag-version.sh b/.gitea/scripts/validate-tag-version.sh new file mode 100755 index 0000000..d239bcb --- /dev/null +++ b/.gitea/scripts/validate-tag-version.sh @@ -0,0 +1,18 @@ +#!/usr/bin/env sh +set -eu + +tag="${1:-}" + +if [ -z "$tag" ]; then + echo "Missing tag ref name (expected vX.Y.Z)." + exit 1 +fi + +version="$(node -p "require('./package.json').version")" + +if [ "$tag" != "v$version" ]; then + echo "Tag/version mismatch: tag=$tag package.json=$version" + exit 1 +fi + +echo "Tag matches package.json version: $tag" diff --git a/README.md b/README.md index ac3377f..df0ed54 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,7 @@ Roadmap and progress are tracked in `TODO.md` (also visible in admin at `/todo`). Branch model and promotion flow are documented in `BRANCHING.md`. Commit schema and changelog workflow are documented in `CONTRIBUTING.md`. +Versioning and release policy are documented in `VERSIONING.md`. A baseline monorepo with: diff --git a/TODO.md b/TODO.md index c92c697..265dbb4 100644 --- a/TODO.md +++ b/TODO.md @@ -84,26 +84,26 @@ This file is the single source of truth for roadmap and delivery progress. - [x] [P2] Theoretical Gitea Actions workflow scaffold (`.gitea/workflows/ci-cd-theoretical.yml`) - [x] [P2] Bun-based Dockerfiles for public and admin apps - [x] [P2] Staging and production docker-compose templates -- [ ] [P1] Registry credentials and image push strategy -- [ ] [P1] Staging deployment automation against real host -- [ ] [P1] Production promotion and rollback procedure +- [x] [P1] Registry credentials and image push strategy +- [x] [P1] Staging deployment automation against real host +- [x] [P1] Production promotion and rollback procedure ### Git Flow And Branching -- [ ] [P1] Protect `main` and `staging` branches in Gitea -- [ ] [P1] Define PR gates: lint + typecheck + unit + e2e list minimum -- [ ] [P1] Enforce one todo item per branch naming convention -- [ ] [P2] Add PR template requiring linked TODO step -- [ ] [P2] Define branch lifecycle for `todo/*`, `refactor/*`, and `code/*` +- [x] [P1] Protect `main` and `staging` branches in Gitea +- [x] [P1] Define PR gates: lint + typecheck + unit + e2e list minimum +- [x] [P1] Enforce one todo item per branch naming convention +- [x] [P2] Add PR template requiring linked TODO step +- [x] [P2] Define branch lifecycle for `todo/*`, `refactor/*`, and `code/*` - [x] [P2] Conventional commit schema documentation (`CONTRIBUTING.md`) - [x] [P2] Changelog scaffold and generation scripts (`CHANGELOG.md`, `bun run changelog:*`) -- [ ] [P1] Versioning policy definition (SemVer strategy + when to bump major/minor/patch) -- [ ] [P1] Source of truth for version (`package.json` root) and release tagging rules (`vX.Y.Z`) -- [ ] [P1] Build metadata policy for git hash (`+sha.`) in app runtime footer -- [ ] [P1] App footer implementation plan for version + commit hash (admin + web) -- [ ] [P2] Automated version injection in CI (stamping build from tag + commit hash) -- [ ] [P2] Validation tests for displayed version/hash consistency per deployment -- [ ] [P1] Release tagging and changelog publication policy in CI +- [x] [P1] Versioning policy definition (SemVer strategy + when to bump major/minor/patch) +- [x] [P1] Source of truth for version (`package.json` root) and release tagging rules (`vX.Y.Z`) +- [x] [P1] Build metadata policy for git hash (`+sha.`) in app runtime footer +- [x] [P1] App footer implementation plan for version + commit hash (admin + web) +- [x] [P2] Automated version injection in CI (stamping build from tag + commit hash) +- [x] [P2] Validation tests for displayed version/hash consistency per deployment +- [x] [P1] Release tagging and changelog publication policy in CI ## MVP 1: Core CMS Business Features @@ -208,6 +208,7 @@ This file is the single source of truth for roadmap and delivery progress. - [2026-02-10] Testing baseline now includes explicit RBAC regression checks, locale-resolution unit tests (admin/web), CRUD service contract tests, and i18n smoke e2e routes. - [2026-02-10] i18n conventions are now documented as an engineering standard (`docs/product-engineering/i18n-conventions.md`). - [2026-02-10] Docs now include a domain glossary, public API glossary, and ADR baseline with initial accepted decision (`ADR 0001`). +- [2026-02-10] Delivery and release governance now include branch/PR policy checks, deploy/release workflows, and explicit versioning policy (`VERSIONING.md`). ## How We Use This File diff --git a/VERSIONING.md b/VERSIONING.md new file mode 100644 index 0000000..edc05fa --- /dev/null +++ b/VERSIONING.md @@ -0,0 +1,71 @@ +# Versioning Policy + +## Source Of Truth + +- Canonical version: root `package.json` field `version` +- Tag format: `vX.Y.Z` + +Tag validation is enforced in CI: + +- `.gitea/scripts/validate-tag-version.sh` + +## SemVer Strategy + +- `major`: breaking API/behavior changes +- `minor`: backward-compatible features +- `patch`: backward-compatible fixes + +## Build Metadata Policy + +Use git metadata in runtime display format: + +- `+sha.` + +Example: + +- `0.1.0+sha.a1b2c3d` + +## Footer Display Plan (Admin + Web) + +Planned runtime footer fields: + +- app name +- version from root `package.json` +- commit hash (short) +- environment (`dev|staging|production`) + +Implementation note: + +- inject values at build/deploy time through env vars +- render in shared footer components + +## CI Version Injection + +Release/deploy workflows pass release tag and commit metadata: + +- `.gitea/workflows/release.yml` +- `.gitea/workflows/deploy.yml` + +Required inputs: + +- release tag (`vX.Y.Z`) +- image tag for deployment + +## Validation Strategy + +CI validations: + +- tag equals `v${package.json.version}` +- required checks pass before release builds + +Runtime validations (planned): + +- smoke tests assert footer version/hash format +- environment-specific deployment checks assert expected image tag + +## Changelog and Release Publication + +- changelog generation command: + - `bun run changelog:release` +- release workflow generates changelog on tag pipeline +- release notes publication remains a dedicated step in CI workflow. diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 90e3279..9a067be 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -27,6 +27,8 @@ export default defineConfig({ { text: "RBAC And Permissions", link: "/product-engineering/rbac-permission-model" }, { text: "Domain Glossary", link: "/product-engineering/domain-glossary" }, { text: "Environment Runbook", link: "/product-engineering/environment-runbook" }, + { text: "Delivery Pipeline", link: "/product-engineering/delivery-pipeline" }, + { text: "Git Flow Governance", link: "/product-engineering/git-flow-governance" }, { text: "Testing Strategy", link: "/product-engineering/testing-strategy" }, { text: "ADR Index", link: "/adr/" }, { text: "Workflow", link: "/workflow" }, diff --git a/docs/index.md b/docs/index.md index 04cd51a..cffb52e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,6 +15,7 @@ Engineering documentation hub for this repository. - Branching and promotion flow: `BRANCHING.md` - Contribution and commit schema: `CONTRIBUTING.md` - Release history: `CHANGELOG.md` +- Versioning and release policy: `VERSIONING.md` ## Documentation Scope diff --git a/docs/product-engineering/index.md b/docs/product-engineering/index.md index 4decf97..5407b4e 100644 --- a/docs/product-engineering/index.md +++ b/docs/product-engineering/index.md @@ -12,6 +12,8 @@ This section covers platform and implementation documentation for engineers and - [CRUD Examples](/product-engineering/crud-examples) - [Domain Glossary](/product-engineering/domain-glossary) - [Environment Runbook](/product-engineering/environment-runbook) +- [Delivery Pipeline](/product-engineering/delivery-pipeline) +- [Git Flow Governance](/product-engineering/git-flow-governance) - [Testing Strategy Baseline](/product-engineering/testing-strategy) - [ADR Index](/adr/) - [Workflow](/workflow)