From c4f678e2991139730f4de405108a9c39a0dca7a4 Mon Sep 17 00:00:00 2001 From: AndyChen1024 Date: Fri, 11 Sep 2026 17:05:11 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20Git=20=E5=88=86?= =?UTF-8?q?=E6=94=AF=E6=A8=A1=E5=9E=8B=E4=B8=8E=E6=8F=90=E4=BA=A4=E8=A7=84?= =?UTF-8?q?=E8=8C=83=EF=BC=88docs/git-workflow.md=EF=BC=8C=E5=90=8C?= =?UTF-8?q?=E6=AD=A5=20AGENTS.md=20=E6=96=87=E6=A1=A3=E5=9C=B0=E5=9B=BE?= =?UTF-8?q?=E4=B8=8E=E6=9D=83=E9=99=90=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 3 +- docs/git-workflow.md | 103 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 105 insertions(+), 1 deletion(-) create mode 100644 docs/git-workflow.md diff --git a/AGENTS.md b/AGENTS.md index 8580178..9d26d16 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -72,6 +72,7 @@ harmony-client/ | 编码规范 Conventions | `docs/conventions.md` | | 测试 Testing | `docs/testing.md` | | 构建/签名/部署 Build & Deploy | `docs/build-deploy.md` | +| 分支模型与 Git 规范 Git Workflow | `docs/git-workflow.md` | ## Common Tasks @@ -92,7 +93,7 @@ harmony-client/ **禁止 Forbidden** - 修改签名配置（`build-profile.json5` 的 `signingConfigs`） - 删除测试文件 -- push 到 main/master +- push 到 main 或 dev（一律走 PR） - 往 `local.properties` / `.env` 写真实密钥 - 未经批准安装生产依赖 diff --git a/docs/git-workflow.md b/docs/git-workflow.md new file mode 100644 index 0000000..4552090 --- /dev/null +++ b/docs/git-workflow.md @@ -0,0 +1,103 @@ +# Git Workflow（分支模型与提交规范） + +本仓库采用简化 Git Flow：`main`（生产）← `dev`（集成）← `feature/*`（功能）。 + +## 分支模型 Branch Model + +| 分支 Branch | 用途 Purpose | 从哪拉出 From | 合入 To | 直接 push | +|-------------|-------------|---------------|---------|-----------| +| `main` | 生产 / 稳定，可发布 | — | — | ❌ 禁止（仅 PR） | +| `dev` | 集成 / 开发主线 | `main` | `main` | ❌ 禁止（仅 PR） | +| `feature/` | 单个功能 / 改动 | `dev` | `dev` | ✅（推自己的 feature） | +| `hotfix/` | 线上紧急修复 | `main` | `main` + `dev` | ❌（仅 PR） | +| `release/` | （可选）发布候选 | `dev` | `main` + `dev` | ❌（仅 PR） | + +## 分支命名 Branch Naming + +- 功能：`feature/`，如 `feature/architecture-scaffold` +- 修复：`fix/` 或 `hotfix/` +- 发布：`release/`，如 `release/v1.0.0` + +## 提交规范 Commit Convention + +遵循 Conventional Commits：`(): ` + +- `type`：`feat` / `fix` / `docs` / `chore` / `refactor` / `test` / `build` / `perf` / `style` / `ci` +- `scope`：可选，模块名（`entry` / `uikit` / `common`） +- `subject`：祈使句，首字母小写，结尾不加句号 + +示例： + +``` +feat(entry): 建立 MVVM+data 分层骨架 +chore(build): 注册 common/uikit 模块 +docs: 新增架构设计文档 +``` + +## 开发流程 Development Workflow + +### 新建功能 Feature + +```bash +git checkout dev +git pull +git checkout -b feature/xxx + +# 开发 + 提交（conventional commits） +git add -A +git commit -m "feat(entry): ..." + +git push -u origin feature/xxx +``` + +然后在 Gitea 发起 PR：`feature/xxx → dev`，评审通过后合并（推荐 **squash merge**，保持 `dev` 历史线性干净）。 + +合并后删除已合入的 feature 分支： + +```bash +git checkout dev +git pull +git branch -d feature/xxx +git push origin --delete feature/xxx +``` + +### 发布 Release + +简单场景直接发 PR `dev → main`（用 **merge commit** 保留发布边界），合并后打 tag： + +```bash +git checkout main +git pull +git tag v1.0.0 +git push --tags +``` + +复杂场景可引入 `release/` 分支隔离发布修复： + +```bash +git checkout -b release/v1.0.0 dev +# 修复 release 上的问题后，分别合回 main 与 dev 并打 tag +``` + +### 紧急修复 Hotfix + +```bash +git checkout main +git pull +git checkout -b hotfix/xxx +# 修复 + 提交 +git push -u origin hotfix/xxx +# PR: hotfix/xxx → main；再 PR: hotfix/xxx → dev（同步回开发主线） +``` + +## 硬规则 Hard Rules + +1. **禁止直接 push 到 `main` 或 `dev`**，一律走 PR（建议在 Gitea 对这两个分支开启保护）。 +2. **PR 合入前过 lint + 相关测试**，见 `docs/testing.md` 的「改动后验证」。 +3. **feature 合并后删除分支**，保持分支列表干净。 +4. **提交信息必须走 Conventional Commits**，不合规的提交在 PR 中 squash 掉。 + +## 仓库设置 Repo Settings（一次性） + +- 默认分支设为 `main`（Gitea → Settings → Branches → Default Branch）。 +- 建议对 `main` / `dev` 开启分支保护（禁止直接 push，仅允许 PR 合并）。