diff --git a/AGENTS.md b/AGENTS.md index 706e1f4..27f489d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -123,7 +123,7 @@ docs/ PRD / 技术架构 / 立项建议 / 工程规范 ## 7 变更流程(提测 / 合并前必须全绿) -1. 从 `main` 拉短分支 → 小步提交(Conventional Commits)。 +1. 从 `main` 拉短分支 → 小步提交(**Conventional Commits,提交信息与 PR 标题一律用中文**,`type` / `scope` 保留英文)。 2. 本地门禁:`pnpm lint && pnpm typecheck && pnpm test`。 3. PR 描述必含:**背景 / 改动 / 影响面 / 回滚方式 / 验证证据**;迁移、权限、AI、导出类变更须**双人 Review**。 4. CI 全绿 + Review 通过 → **Squash Merge**;禁止 force push `main`。 @@ -147,7 +147,7 @@ docs/ PRD / 技术架构 / 立项建议 / 工程规范 | 主题 | 文档 | 一句话 | | --- | --- | --- | -| Git / 分支 / 提交 | [01-Git规范](docs/工程规范/01-Git规范.md) | 主干 + 短分支,Conventional Commits,Squash 合并 | +| Git / 分支 / 提交 | [01-Git规范](docs/工程规范/01-Git规范.md) | 主干 + 短分支,Conventional Commits(**提交信息用中文**),Squash 合并 | | 代码风格 | [02-代码风格](docs/工程规范/02-代码风格.md) | 命名、类型、错误处理、异步、React 约定 | | 格式化与 Lint | [03-格式化与Lint](docs/工程规范/03-格式化与Lint.md) | Prettier + ESLint 9 flat,钩子与 CI 门禁 | | API 与路由 | [04-API与路由规范](docs/工程规范/04-API与路由规范.md) | REST /api/v1、错误码、鉴权链、任务协议 | @@ -201,7 +201,7 @@ docs/ PRD / 技术架构 / 立项建议 / 工程规范 ## 附:待同步事项(2026-11-02) - [x] 根 `README.md` 已与 PRD V1.6 对齐(三主线 + 一底座、文档索引、命令契约)。 -- [ ] `docs/技术架构/`、`docs/立项建议/`、PRD V1.6、`docs/工程规范/` 尚未纳入 git,应合并为一个 `docs:` 提交入库。 +- [x] `docs/技术架构/`、`docs/立项建议/`、PRD V1.6、`docs/工程规范/` 已于 2026-11-02 按 Conventional Commits 拆为 6 个提交入库并推送(`6f644c0`~`c50ee7b`)。 - [ ] PRD 文件名 `灵犀-信息流广告素材一站式生产平台PRD.md` 不符合 §8 命名;因已被外部引用,暂保留原名,重命名时同步更新全部引用。 - [ ] 技术架构文档**文件名**为 `_V0.1.md` 但**内部版本**为 V0.4,正文修订记录中 V0.4 / V0.3 顺序倒置,建议下一版修正。 diff --git a/docs/工程规范/01-Git规范.md b/docs/工程规范/01-Git规范.md index fc5cfc2..9777cb5 100644 --- a/docs/工程规范/01-Git规范.md +++ b/docs/工程规范/01-Git规范.md @@ -34,9 +34,9 @@ ## 2 提交信息(Conventional Commits 1.0) ``` -(): +(): <中文简述> - + ``` @@ -57,7 +57,7 @@ 规则: -- `GIT-05` `subject` 用英文祈使句,≤ 72 字符,**不加句号**;中文放正文。 +- `GIT-05` 提交信息(`subject` + 正文)**一律使用中文**;`type` / `scope` 保留英文小写。`subject` 用祈使句(「新增 …」而非「新增了 …」「新增的 …」),≤ 50 个汉字且整行 ≤ 72 字符,**不加句末标点**(英文 `.` 与中文 `。` 均禁止)。 - `GIT-06` `scope` 必填,取值见 `GIT-01`。 - `GIT-07` 正文说明「**为什么**」与「**影响面 / 回滚方式**」;纯重命名类可仅一行 subject。 - `GIT-08` 破坏性变更:`type` 后加 `!` 且 footer 写 `BREAKING CHANGE: <说明与迁移方式>`。 @@ -79,6 +79,30 @@ feat(media): 图片批次支持按规格矩阵展开任务项 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 PR 与合并 @@ -115,7 +139,7 @@ Refs: R-25 ## 6 检查清单(提交前 / 合并前) - [ ] 分支名符合 `GIT-01`,从最新 `main` 拉出 -- [ ] 提交信息符合 Conventional Commits,含 `scope` +- [ ] 提交信息为**中文**且符合 Conventional Commits(含 `scope`),subject 无句末标点 - [ ] 提交粒度单一,无无关文件 - [ ] 无 `.env` / 密钥 / 大文件 - [ ] PR 描述含背景 / 影响面 / 回滚方式 / 验证证据 diff --git a/docs/工程规范/03-格式化与Lint.md b/docs/工程规范/03-格式化与Lint.md index 4ba281b..9eb1458 100644 --- a/docs/工程规范/03-格式化与Lint.md +++ b/docs/工程规范/03-格式化与Lint.md @@ -91,7 +91,7 @@ element-plus naive-ui @mui/* @chakra-ui/* | 钩子 | 工具 | 行为 | | --- | --- | --- | | `pre-commit` | husky + lint-staged | 仅对暂存文件跑 `eslint --fix` + `prettier --write` | -| `commit-msg` | commitlint | 校验 Conventional Commits(见 [01](01-Git规范.md) §2) | +| `commit-msg` | commitlint | 校验 Conventional Commits 与中文书写(配置见 [01](01-Git规范.md) §2.2) | | `pre-push` | husky | 跑 `pnpm typecheck`(本地拦截类型错误,避免浪费 CI) | - `FMT-08` `lint-staged` 只处理暂存文件,**禁止**在钩子里跑全量 lint / 全量测试(太慢会诱发 `--no-verify`)。 diff --git a/docs/工程规范/07-CodeReview与PR规范.md b/docs/工程规范/07-CodeReview与PR规范.md index c85ca1a..ff9a2d6 100644 --- a/docs/工程规范/07-CodeReview与PR规范.md +++ b/docs/工程规范/07-CodeReview与PR规范.md @@ -32,7 +32,7 @@ - 迁移在 staging 的执行结果 ``` -- `PR-01` 标题遵循 Conventional Commits(Squash 后即主干提交)。 +- `PR-01` 标题遵循 Conventional Commits 且**用中文**(Squash 时以 PR 标题为准,`scope` 保留英文,写法见 [01](01-Git规范.md) §2)。 - `PR-02` 变更 ≤ 400 行(不含 lock / 生成代码);超出拆分为多个 PR 并在描述写依赖顺序。 - `PR-03` 禁止在功能 PR 中混入无关重构、格式化、依赖升级。 - `PR-04` Draft PR 可用于早期讨论,但**不得**在 CI 未绿时请求 Review。 diff --git a/docs/工程规范/README.md b/docs/工程规范/README.md index 3dbc12d..af8a1be 100644 --- a/docs/工程规范/README.md +++ b/docs/工程规范/README.md @@ -20,7 +20,7 @@ | 项 | 约定 | | --- | --- | -| 编写语言 | 中文说明 + 英文标识符 / 命令 / 路径 | +| 编写语言 | 中文说明 + 英文标识符 / 命令 / 路径;**Git 提交信息与 PR 标题也用中文**(见 [01](01-Git规范.md) §2) | | 结构 | 作用与边界 → 规则(表格 / 编号)→ 检查清单 → 违规示例 | | 变更 | 修改规则须单独 PR,说明「为什么改」+「存量代码如何处理」 | | 版本 | `V<主>.<次>`;主版本 = 破坏性(存量代码需整改),次版本 = 补充 |