# 01 · Git 规范

| 项 | 内容 |
| --- | --- |
| 文档版本 | V1.1（2026-11-02） |
| 依据 | 技术架构 §4.6（CI/CD）、§10.1（仓库结构） |
| 适用范围 | 全仓库（代码、文档、配置、迁移） |
| 强制级别 | 强制 |

---

## 1　分支模型

采用 **仅 main 直推**：仓库只保留 `main` 一条分支，不建 `develop`、`release`、`feat/*`、`docs/*` 等任何本地或远程分支。

| 类型 | 名称   | 用途                     | 生命周期 |
| ---- | ------ | ------------------------ | -------- |
| 主干 | `main` | 唯一长期分支，始终可发布 | 永久     |

规则：

- `GIT-01` 所有提交直接基于最新 `main`；提交前先 `git pull --ff-only`，避免落后。
- `GIT-02` 禁止创建并推送任何非 `main` 分支；确需本地验证时可临时创建，但不得推送，完成后立即删除。
- `GIT-03` 允许直接 push `main`；推送前必须通过本地门禁（`format:check`、`lint`、`typecheck`、`test`，完整链路用 `pnpm ci:local`）。**远端 Gitea 未部署 runner，线上 CI 不可用，推送后不等待远端 CI**。
- `GIT-04` 禁止 force push `main`；禁止 Merge commit；`main` 必须保持线性。

## 2　提交信息（Conventional Commits 1.0）

```
<type>(<scope>): <中文简述>

<body：中文，说明为什么改 + 影响面 / 回滚方式>

<footer：BREAKING CHANGE / Refs: R-xx / Closes #12>
```

| `type` | 用途 |
| --- | --- |
| `feat` | 新功能 |
| `fix` | 缺陷修复 |
| `docs` | 文档 |
| `style` | 仅格式（不影响逻辑） |
| `refactor` | 重构（不改行为） |
| `perf` | 性能 |
| `test` | 测试 |
| `build` | 构建 / 依赖 |
| `ci` | CI / 脚本 |
| `chore` | 杂项 |
| `revert` | 回滚 |

规则：

- `GIT-05` 提交信息（`subject` + 正文）**一律使用中文**；`type` / `scope` 保留英文小写。`subject` 用祈使句（「新增 …」而非「新增了 …」「新增的 …」），≤ 50 个汉字且整行 ≤ 72 字符，**不加句末标点**（英文 `.` 与中文 `。` 均禁止）。
- `GIT-06` `scope` 必填，取值见 `GIT-01`。
- `GIT-07` 正文说明「**为什么**」与「**影响面 / 回滚方式**」；纯重命名类可仅一行 subject。
- `GIT-08` 破坏性变更：`type` 后加 `!` 且 footer 写 `BREAKING CHANGE: <说明与迁移方式>`。
- `GIT-09` 关联业务规则写 `Refs: R-04`；关联 issue 写 `Closes #123`。
- `GIT-10` 一个提交只做一件事；**禁止**在功能提交里顺带格式化无关文件。
- `GIT-11` 禁止 `WIP`、`fix bug`、`update` 等无信息量信息；禁止 `--no-verify` 绕过钩子。

示例：

```
feat(media): 图片批次支持按规格矩阵展开任务项

批量生产原先按「模板 × 商品图」展开，导致同素材多规格重复建素材，
违反 PRD R-25「素材为主对象、规格为属性」。改为展开到 task_item，
规格作为属性写入 material_specs。

影响面：production_tasks 新增 spec_key 列（expand 迁移，兼容旧数据）。
回滚方式：关闭 FEATURE_MATRIX_SPEC 开关，旧路径仍可用。
Refs: R-25
```

### 2.1 中文书写与中英混排（GIT-21 ~ GIT-23）

- `GIT-21` 中文与英文 / 数字之间**加一个空格**（`新增 PRD V1.6`、`导出 50 张图`）；标点用中文全角；代码、命令、文件名、版本号、错误码用反引号包裹并保留原文。
- `GIT-22` 术语沿用 PRD 附录 C 术语表，**禁止自造同义词**（「素材规格」不写「素材尺寸」，「要素卡」不写「简报卡」）。
- `GIT-23` 禁止 Chinglish 与无信息缩写：不写 `add 功能 for batch`、`opt`、`tmp`、`misc`、`update`；`type` / `scope` 之外的英文只能是专有名词、标识符或引用编号。

### 2.2 commitlint 配置要点

中文提交信息有三个坑，必须在 `commitlint.config.mjs` 中显式处理，否则校验形同无效：

```js
export default {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'subject-case': [0],                       // 中文无大小写概念，关闭该规则
    'header-max-length': [2, 'always', 72],    // 按字符计，中文每个字计 1
    'subject-full-stop': [2, 'never', '。'],   // 拦截中文句号
    'subject-empty': [2, 'never'],
  },
};
```

> 对应的 husky `commit-msg` 钩子见 [03-格式化与Lint](03-格式化与Lint.md) §4。

---

## 3　提交、推送与 Review

- `GIT-12` 直接推送到 `main` 的提交即主干提交，提交信息按 §2 执行。
- `GIT-13` 禁止 Merge commit 等分支合并方式；一次提交只做一件事，`main` 保持线性。
- `GIT-14` 单个提交变更 ≤ 400 行（含测试，不含 lock 与生成代码）；里程碑批次超出须在提交说明注明原因与拆分计划。
- `GIT-15` 禁止 force push `main`；已推送提交不回改写，修复一律用新提交前向修复。
- `GIT-16` Review 要求见 [07-CodeReview与PR规范](07-CodeReview与PR规范.md)：高风险变更推送前完成双人走查，普通变更至少自查并在推送后 24 小时内走查。

## 4　Tag 与发布

| 项 | 规则 |
| --- | --- |
| 版本号 | 语义化 `v<主>.<次>.<补>` |
| 打 Tag 时机 | 生产发布前，由发布负责人在 `main` 打 annotated tag |
| 里程碑 Tag | `m0` / `m1` / `m2`…（对应 PRD 分期），仅标记不进版本链 |
| 发布记录 | 每个 Tag 必须写变更摘要（可复用提交标题集合） |
| 回滚 | 回滚用新 Tag（`v1.2.1` 回滚 `v1.2.0` 内容），**禁止删除已发布 Tag** |

---

## 5　大文件与二进制

- `GIT-17` 禁止入库 > 10 MB 的二进制（PSD 模板、成片、视频、字体包），一律走对象存储；确需入库（如开源字体）用 **Git LFS** 并在提交说明。
- `GIT-18` 禁止入库：`.env*`、密钥、证书私钥、构建产物、`node_modules/`、日志、`项目参考/`。
- `GIT-19` `pnpm-lock.yaml` 必须提交且与 `package.json` 同步；**禁止**手工编辑 lock 文件。
- `GIT-20` 误提交敏感信息：立即轮换密钥 → 用 `git filter-repo` 清理历史 → 全员重新 clone → 记录复盘。

---

## 6　检查清单（提交前 / 推送前）

- [ ] 提交基于最新 `main`，已同步远端
- [ ] 提交信息为**中文**且符合 Conventional Commits（含 `scope`），subject 无句末标点
- [ ] 提交粒度单一，无无关文件
- [ ] 无 `.env` / 密钥 / 大文件
- [ ] 提交说明含背景 / 影响面 / 回滚方式 / 验证证据
- [ ] 本地门禁全绿（必要时 `pnpm ci:local`），已 push `main`；远端无 CI，无需等待