From 244c4241264823568bb3f3eebcef690c8fb2c017 Mon Sep 17 00:00:00 2001
From: Cheng Zhou <zhoucheng857@gmail.com>
Date: Mon, 30 Mar 2026 16:59:48 +0800
Subject: [PATCH] docs: add branch governance policy

---
 README.md                 |   4 +
 docs/branch-governance.md | 340 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 344 insertions(+)
 create mode 100644 docs/branch-governance.md

diff --git a/README.md b/README.md
index 8514c96c..067637b1 100644
--- a/README.md
+++ b/README.md
@@ -30,6 +30,10 @@
 - 前端：`http://localhost`（Nginx 直接托管前端静态文件）
 - 后端 API：同域 `/api/v1/*`（已在前端代理）
 
+## 仓库治理文档
+- 分支治理规范：`docs/branch-governance.md`
+- 发布检查清单：`docs/release-checklist.md`
+
 ## 常用流程
 1. 用管理员账号登录前端（默认 `admin@example.com / admin123`）。
 2. 进入左侧导航「账号治理」「项目治理」进行用户、项目、中心等全局管理；或在“项目列表”选择项目后进入项目内工作区。
diff --git a/docs/branch-governance.md b/docs/branch-governance.md
new file mode 100644
index 00000000..a98b599e
--- /dev/null
+++ b/docs/branch-governance.md
@@ -0,0 +1,340 @@
+# CTMS Git Branch Governance
+
+## 1. Purpose
+
+This document defines the long-term Git branch governance model for the CTMS repository.
+
+The goals are:
+
+- keep daily development efficient on `dev`
+- keep `main` readable as the next major version baseline
+- keep `release` stable and suitable for production maintenance
+- make release, hotfix, and back-merge behavior explicit
+
+This document is the default branch management policy unless a later written rule supersedes it.
+
+## 2. Branch Roles
+
+### `dev`
+
+`dev` is the daily development and integration branch.
+
+Use cases:
+
+- feature development
+- exploratory changes
+- internal integration and verification
+- non-release refactors
+
+Characteristics:
+
+- accepts frequent commits
+- may contain incomplete but merge-approved work
+- history can be relatively dense
+
+### `main`
+
+`main` is the candidate primary version branch.
+
+Use cases:
+
+- preparing the next formal release
+- staging a version for full regression, acceptance, or external integration
+- holding a clean version-level history of what is intended to go to production next
+
+Characteristics:
+
+- must remain deployable in principle
+- should only receive changes that are judged release-candidate quality
+- should be cleaner than `dev` in both content and history
+
+### `release`
+
+`release` is the long-lived production stability branch.
+
+Use cases:
+
+- current production version
+- urgent production hotfixes
+- maintenance of already released code
+
+Characteristics:
+
+- strongest stability requirement
+- no routine feature development
+- every production release should be identifiable by tag
+
+## 3. Promotion Path
+
+The default code promotion path is:
+
+`feature/*` -> `dev` -> `main` -> `release`
+
+Meaning:
+
+- daily work enters `dev`
+- stable milestone scope is promoted from `dev` to `main`
+- approved release scope is promoted from `main` to `release`
+
+Direct promotion that skips stages is discouraged and must be justified in writing.
+
+## 4. Branch Entry Rules
+
+### Changes allowed into `dev`
+
+Allowed:
+
+- feature branches
+- refactors
+- test improvements
+- integration work
+- exploratory work that has passed review
+
+Requirements:
+
+- code review completed
+- no known blocking regression introduced intentionally without team alignment
+- relevant tests pass at the feature or module level
+
+### Changes allowed into `main`
+
+Allowed:
+
+- version-ready content promoted from `dev`
+- tightly scoped fixes required to stabilize the next version
+
+Requirements:
+
+- scope is explicitly selected for the next release candidate
+- regression testing has been run for the affected area
+- release-risking incomplete work must be excluded
+- merge should represent a coherent version increment, not random unfinished work
+
+### Changes allowed into `release`
+
+Allowed:
+
+- approved production releases from `main`
+- hotfixes for production incidents
+
+Requirements:
+
+- release checklist completed
+- production-facing validation completed
+- change is either a formal release or a critical maintenance fix
+
+Routine feature work must not be merged directly into `release`.
+
+## 5. Merge Strategy
+
+### `feature/*` -> `dev`
+
+Preferred strategy:
+
+- pull request merge or rebase merge
+
+Rules:
+
+- branch should be reasonably scoped
+- commit history can be preserved
+- reviewer may require cleanup for obviously noisy commits
+
+### `dev` -> `main`
+
+Preferred strategy:
+
+- squash merge
+
+Rationale:
+
+- preserve detailed development history on `dev`
+- keep `main` at a version or milestone granularity
+- avoid making `main` a duplicate of `dev` commit-for-commit
+
+Rules:
+
+- each merge to `main` should correspond to a named milestone, candidate, or release scope
+- squash commit message should describe the version or milestone clearly
+
+Recommended commit format:
+
+- `release(main): prepare v1.2.0 candidate`
+- `release(main): integrate Q2 CTMS milestone`
+
+### `main` -> `release`
+
+Preferred strategy:
+
+- normal merge commit
+
+Rationale:
+
+- preserve the relationship between the released state and the accepted candidate branch
+- make production promotion traceable
+
+Rules:
+
+- merge only after acceptance and release checks
+- create a version tag immediately after the release merge
+
+### `hotfix/*` -> `release`
+
+Preferred strategy:
+
+- normal merge commit
+
+Rules:
+
+- branch must be narrowly scoped to the production issue
+- branch name should identify the production problem clearly
+
+Examples:
+
+- `hotfix/login-timeout-loop`
+- `hotfix/admin-init-guard`
+
+## 6. Tag Rules
+
+Every formal production release on `release` must be tagged.
+
+Recommended format:
+
+- `v1.0.0`
+- `v1.1.0`
+- `v1.1.1`
+
+Tag semantics:
+
+- major: incompatible or structurally significant release
+- minor: backward-compatible feature release
+- patch: backward-compatible hotfix release
+
+Rules:
+
+- tags are created on `release`, not on `dev`
+- a tag must point to the exact production release commit
+- patch hotfixes on `release` should increment the patch version
+
+## 7. Hotfix Back-Merge Rules
+
+Every hotfix merged into `release` must be merged back into both `main` and `dev`.
+
+Required follow-up path:
+
+`hotfix/*` -> `release` -> `main` -> `dev`
+
+Rules:
+
+- do not assume the fix already exists elsewhere
+- perform the back-merge as soon as the production fix is verified
+- if conflicts occur, resolve them immediately and document the resolution in the pull request or release record
+
+This rule prevents production fixes from being lost in later development cycles.
+
+## 8. Branch Protection Recommendations
+
+### Protect `release`
+
+Recommended controls:
+
+- no direct push
+- pull request required
+- at least one reviewer required
+- status checks required
+- tag creation restricted to release maintainers if platform settings allow
+
+### Protect `main`
+
+Recommended controls:
+
+- no direct push
+- pull request required
+- at least one reviewer required
+- regression or build checks required before merge
+
+### Manage `dev`
+
+Recommended controls:
+
+- direct push discouraged
+- pull request preferred
+- team may allow limited direct push for maintainers during active integration windows
+
+If direct push is temporarily allowed on `dev`, it should remain an exception rather than the default workflow.
+
+## 9. Release Readiness Criteria
+
+Before promoting `dev` to `main`, confirm:
+
+- selected feature scope is complete
+- known blockers are resolved or explicitly deferred
+- affected tests pass
+- acceptance scope is defined
+
+Before promoting `main` to `release`, confirm:
+
+- release checklist is complete
+- production initialization, build, and smoke verification are complete
+- rollback or remediation path is clear
+- release tag has been prepared
+
+Reference:
+
+- [docs/release-checklist.md](/Users/zcc/MyCTMS/ctms-dev/docs/release-checklist.md)
+
+## 10. Standard Workflow Examples
+
+### New feature
+
+1. create `feature/<name>` from `dev`
+2. develop and review against `dev`
+3. merge into `dev`
+4. when milestone scope is stable, squash merge selected scope from `dev` to `main`
+5. run candidate validation on `main`
+6. merge `main` into `release`
+7. create production tag on `release`
+
+### Production hotfix
+
+1. create `hotfix/<name>` from `release`
+2. fix and validate only the production issue
+3. merge into `release`
+4. tag patch version on `release`
+5. back-merge the same fix into `main`
+6. back-merge the same fix into `dev`
+
+## 11. Current Repository Mapping
+
+For the current CTMS repository, the intended meaning is:
+
+- `dev`: ongoing development branch
+- `main`: next candidate major version branch
+- `release`: long-lived stable production branch
+
+Current local workspace layout:
+
+- primary repository: `/Users/zcc/MyCTMS/ctms-dev` on `dev`
+- `main` worktree: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main`
+- `release` worktree: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/release`
+
+Current remote default branch:
+
+- `origin/HEAD` points to `origin/main`
+
+If `dev` and `main` temporarily point to the same commit, that is acceptable as a transition state.
+
+The governance target is not to keep them permanently identical. The target is:
+
+- `dev` keeps detailed development history
+- `main` keeps milestone-level release-candidate history
+- `release` keeps production-approved history with tags
+
+## 12. Non-Goals
+
+This policy does not require:
+
+- rewriting branch history to a single commit
+- forcing `main` to always differ from `dev`
+- maintaining a separate release branch per version unless future scale requires it
+
+The policy prioritizes traceability, stable promotion, and predictable maintenance over artificially minimal history.