From 1e2fbbccb08086d9ed67ac3f19eb74ae1d5d2fb1 Mon Sep 17 00:00:00 2001 From: wushumin Date: Wed, 3 Jun 2026 21:46:54 +0800 Subject: [PATCH] docs: add branch workflow management rules --- .claude/skills/project-management/SKILL.md | 72 +++++++++++++++++++++ README.md | 1 + docs/development/branch-workflow.md | 73 ++++++++++++++++++++++ 3 files changed, 146 insertions(+) create mode 100644 .claude/skills/project-management/SKILL.md create mode 100644 docs/development/branch-workflow.md diff --git a/.claude/skills/project-management/SKILL.md b/.claude/skills/project-management/SKILL.md new file mode 100644 index 0000000..e40be58 --- /dev/null +++ b/.claude/skills/project-management/SKILL.md @@ -0,0 +1,72 @@ +--- +name: project-management +description: Use when managing the Anxinyan project at /Users/wushumin/www/biyou/anxinyan, especially Git branch workflow, collaboration rules, commits, pre-submit checks, GitNexus detect-changes, release branch handling, or deciding where project-management rules belong. +--- + +# 安心验项目管理规范 + +Project root: `/Users/wushumin/www/biyou/anxinyan`. + +Use the outer repository as the single source of truth for all project work. Do not create separate Git branch systems inside `server-api`, `admin-web`, `user-app`, or `work-app`. + +Do not manage release artifacts in Git. Files under `releases/`, including zip packages, APKs, and checksum files, are local delivery artifacts and must not be committed or pushed. + +## Branch Model + +- `master`: stable, release-ready mainline. Do not do daily development directly here. +- `develop`: integration branch for normal multi-person development. +- `feature/-`: feature or improvement branches created from `develop`. +- `release/`: release stabilization branches created from `develop`. +- `hotfix/`: urgent production fixes created from `master`. + +After repository initialization, keep the local checkout on `develop` for daily work. + +## Standard Workflows + +For normal work: + +1. Start from updated `develop`. +2. Create a `feature/-` branch. +3. Commit focused changes with clear Conventional Commits messages. +4. Open a merge request back to `develop`. +5. Include changed surfaces, verification commands, and risk notes in the merge request. + +For releases: + +1. Create `release/` from `develop`. +2. Keep the release branch limited to release blockers, verification fixes, and docs. +3. Merge the verified release branch to `master`. +4. Merge `master` back into `develop`. + +For hotfixes: + +1. Create `hotfix/` from `master`. +2. Fix only the production issue. +3. Merge to `master` for release. +4. Merge `master` back into `develop`. + +## Required Checks + +Before committing, run: + +```bash +git status -sb +git diff --check +npx gitnexus detect-changes --scope all +``` + +Before changing code symbols, follow the repository `AGENTS.md` GitNexus rule: run upstream impact analysis for the target symbol and report the blast radius. Before committing any change, run GitNexus detect changes. + +For release packaging or deployment preparation, also follow the release checklist and packaging skill. At minimum, run the relevant backend smoke/audit scripts and frontend checks for the surfaces touched. + +Release packages should stay under the ignored local `releases/` directory and be handed off separately from Git branches. + +## Documentation Source + +The human-readable branch workflow is documented in: + +```text +docs/development/branch-workflow.md +``` + +Keep this skill and that document aligned when branch rules change. diff --git a/README.md b/README.md index 5897f61..90cc048 100644 --- a/README.md +++ b/README.md @@ -71,3 +71,4 @@ npm run build - [履约冒烟检查表](/Users/wushumin/www/biyou/anxinyan/docs/deploy/fulfillment-smoke-checklist.md) - [当前交付说明](/Users/wushumin/www/biyou/anxinyan/docs/deploy/delivery-notes.md) - [部署说明](/Users/wushumin/www/biyou/anxinyan/docs/deploy/deploy-plan.md) +- [分支协作规范](/Users/wushumin/www/biyou/anxinyan/docs/development/branch-workflow.md) diff --git a/docs/development/branch-workflow.md b/docs/development/branch-workflow.md new file mode 100644 index 0000000..f1ad91c --- /dev/null +++ b/docs/development/branch-workflow.md @@ -0,0 +1,73 @@ +# 安心验分支协作规范 + +本项目使用最外层 Git 仓库统一管理 `server-api`、`admin-web`、`user-app`、`work-app` 和文档。不要在子目录中单独维护分支体系；涉及多端联动的需求应放在同一个功能分支和合并请求中，方便评审、测试、发版和回滚。 + +`releases/` 下的 zip、apk、校验文件等发布产物只作为本地交付物管理，不纳入 Git 分支管理范围，也不要提交或推送到远程仓库。 + +## 长期分支 + +| 分支 | 用途 | 维护规则 | +| --- | --- | --- | +| `master` | 稳定主线，代表已经验证、可发布的状态 | 禁止日常直接开发；通过合并请求进入 | +| `develop` | 多人开发集成分支 | 日常功能从这里拉分支，完成后合回这里 | + +初始化完成后，本地默认停留在 `develop`。日常开发不要直接在 `master` 上提交业务代码。 + +## 临时分支 + +| 分支模式 | 用途 | 来源 | 合并目标 | +| --- | --- | --- | --- | +| `feature/-` | 普通需求或优化 | `develop` | `develop` | +| `release/` | 发版冻结和发布修复 | `develop` | `master`，再回合 `develop` | +| `hotfix/` | 线上紧急修复 | `master` | `master`，再回合 `develop` | + +`scope` 建议使用端或模块名，例如 `api`、`admin`、`user`、`work`、`docs`、`fulfillment`、`report`。示例： + +```bash +git switch develop +git pull --ff-only +git switch -c feature/admin-report-export +``` + +## 日常开发流程 + +1. 从 `develop` 更新最新代码。 +2. 创建 `feature/-` 分支。 +3. 在功能分支提交改动，提交信息使用清晰的 Conventional Commits 风格，例如 `feat: add report export`。 +4. 提交合并请求到 `develop`，说明涉及的端、业务入口、验证结果和风险点。 +5. 合并前保持分支基于最新 `develop`，优先使用正常 merge 或 rebase，禁止强推公共协作分支。 + +## 提交前检查 + +所有提交前至少完成： + +```bash +git status -sb +git diff --check +npx gitnexus detect-changes --scope all +``` + +如果修改了 PHP 后端文件，补充运行相关 PHP 语法检查或项目脚本；如果修改了前端，按影响端运行对应的类型检查或构建。发版前按上线检查清单执行 `server-api/tools/release_audit.php`、`server-api/tools/smoke_check.php` 和相关客户端构建。 + +发布包生成后保留在本地 `releases/` 目录并按需另行交付；Git 提交中不包含 release 包。 + +## 发版流程 + +1. 从最新 `develop` 创建 `release/`。 +2. 在 release 分支只接受发布必要修复、配置核对和文档更新。 +3. 通过上线检查后，将 release 分支合并到 `master` 并打 tag。 +4. 将 `master` 的发布结果回合到 `develop`，保证开发线包含发布修复。 + +## Hotfix 流程 + +1. 从最新 `master` 创建 `hotfix/`。 +2. 只修改线上故障必需内容，避免夹带普通需求。 +3. 验证通过后合并到 `master` 并发布。 +4. 立即将 `master` 回合到 `develop`，避免同一问题在后续版本中回退。 + +## Gitea 仓库设置 + +- 默认分支设为 `master`。 +- 保护 `master`，要求通过合并请求进入。 +- 建议保护 `develop`；团队早期可以只限制普通成员直接 push。 +- 不提前保护 `feature/*`、`release/*`、`hotfix/*`，按团队规模和协作习惯逐步增加规则。