From 027876ae002bae676ea02d53c38a143daa221eb8 Mon Sep 17 00:00:00 2001 From: Lixi20 Date: Fri, 4 Sep 2026 10:36:34 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=A2=9E=E5=8A=A0=20Git=20=E5=B7=A5?= =?UTF-8?q?=E4=BD=9C=E6=B5=81=E8=A7=84=E8=8C=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 三仓分支模型（api/flutter 以 dev 为集成分支、doc 直接 main）、feature 分支时机 - 固化中文语义前缀提交约定：正文写验收证据、引用 ADR 编号 - 禁止事项：敏感配置/构建产物不入库、共享分支不 force push、已推送 Flyway 迁移不可变（呼应开发计划 4.3） - 按仓库分列提交前本地门禁命令清单，作为未来 CI 门禁蓝本 - 门禁：mkdocs build --strict 通过（零 warning） Co-Authored-By: Claude Fable 5 --- docs/development/git-workflow.md | 43 ++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 44 insertions(+) create mode 100644 docs/development/git-workflow.md diff --git a/docs/development/git-workflow.md b/docs/development/git-workflow.md new file mode 100644 index 0000000..a737ee8 --- /dev/null +++ b/docs/development/git-workflow.md @@ -0,0 +1,43 @@ +# Git 工作流规范 + +适用于三个仓库：`patbond-api`（dev）、`patbond-flutter`（dev）、`patbond-doc`（main）。 + +## 分支模型 + +- **patbond-api / patbond-flutter**：`dev` 为集成分支，保持随时可构建（门禁全绿）。日常改动小步直接提交到 `dev`。 +- **patbond-doc**：直接提交 `main`。 +- **何时开 feature 分支**：改动跨多天、有破坏性风险（如大规模重构、依赖升级）、或多人并行同一仓库时，从最新 `dev` 拉出 `feat/<主题>` / `fix/<主题>` 分支，完成后合回并删除分支。短命分支，不留长期分叉。 + +## 提交信息约定 + +格式：`<前缀>: <中文主题>`，前缀取 `feat` / `fix` / `refactor` / `docs` / `test` / `chore`。 + +- 主题一句话说清做了什么；涉及架构决策时在主题或正文引用 ADR 编号（如 `（ADR-005）`）。 +- 正文用列表写关键改动与**验收证据**（测试数量与结果、门禁命令输出结论），让提交自证可用。 +- 一次提交做一件事，可独立回退；不把无关改动混进同一提交。 + +示例（既有惯例）： + +```text +feat: 迁移珊瑚橙主题体系并新增认证基础组件（ADR-005） + +- 新增 BrandMark/AppTextField 等 5 个组件及 6 个 widget 测试 +- 门禁：dart format（0 changed）/ flutter analyze（0 issues）/ flutter test（7 passed） +``` + +## 禁止事项 + +- **不提交敏感配置与构建产物**：本地 `application.yml`、`target/`、`build/`、`.dart_tool/`、`.idea/`、密钥凭据一律不入库（.gitignore 已覆盖，提交前 `git status` 逐一核对暂存清单）。配置只提交 `*.sample`。 +- **不 force push 共享分支**（`dev` / `main`）。个人 feature 分支整理历史后如需强推，用 `git push --force-with-lease`。 +- **不修改已推送的 Flyway 迁移**（呼应开发计划 4.3 节）：`V1__*.sql` 等已进入 `dev` 的版本化迁移视为不可变，schema 变更一律新增 `V__*.sql`。 +- 不改写已推送的提交历史（rebase/amend 仅限未推送内容）。 + +## 提交前本地门禁（未来 CI 将执行同一清单） + +| 仓库 | 必跑命令 | 通过标准 | +| --- | --- | --- | +| patbond-api | `JAVA_HOME=/usr/lib/jvm/java-17-openjdk ./mvnw clean test` | BUILD SUCCESS，0 失败（需 Docker 供 Testcontainers） | +| patbond-flutter | `dart format --output=none --set-exit-if-changed lib test`
`flutter analyze`
`flutter test` | 0 changed / No issues / All tests passed | +| patbond-doc | `mkdocs build --strict -d <临时目录>` | exit 0，零 warning；不把 `site/` 落进仓库 | + +门禁不绿不提交。CI 载体（审计 M3 后半）落地后将原样执行上表命令作为合入门禁。 diff --git a/mkdocs.yml b/mkdocs.yml index a072cf1..d619766 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,5 +5,6 @@ nav: - 首页: index.md - 开发文档: - 开发实施计划: development/development-plan.md + - Git 工作流规范: development/git-workflow.md - 架构: - 技术决策记录: architecture/decisions.md