git-commit-standard

# git-commit-standard ## 强制依赖 **加载本 skill 时必须同时加载以下 skill 并严格遵循其规范：** - `git-commit-template` — 定义 commit message 的模板、字段和写作风格。 - `model-version-locator` — 定位当前机型宏和版本号。优先使用此 skill 自动发现版本信息，而不是手动搜索 `*_cfg.h` 文件。 本 skill 定义提交流程和门禁。 ## Overview 用于执行仓库约定的提交、版本、固件产物归档和 changelog/release record 同步。核心原则：**提交前先确认仓库规则，再默认检查并同步版本元数据、README/changelog、固件产物和发布记录，最后 commit**。 **默认行为（最高优先级）：每次执行任何 commit 相关操作时，只要存在代码改动，就必须先重新编译并更新最新固件产物，再同步 README/changelog 总结。** 这条规则对 `commit` 和 `amend` 一视同仁，不受是否修改版本号影响；它是本 skill 的硬性门禁，不能当作额外功能、可选增强或 commit message 里的“变更点”。只有仓库规则、用户明确要求或历史证据明确证明本次没有对应固件/README/changelog 记录项时，才可跳过，并在执行记录中说明依据。禁止把“未递进版本”“只是 amend”“只是 fix/中间提交”作为跳过固件或履历同步的理由。 该 skill 设计为通用技能：不要写死某个仓库的版本头、固件目录、构建宏、产物命名或 README 路径；这些信息必须从当前仓库的配置、AGENTS.md、历史提交和实际文件结构中推导或维护。 ## When to Use 必须使用： - 用户明确要求遵循标准提交流程。 - 用户说"按标准流程提交""按提交流程提交"等精确触发词。注意：普通提交请求（如"提交""提交一下""commit"）不应匹配本 skill——这些请求仅应加载 `git-commit-template`，不得触发版本递进确认、固件重编译等本 skill 的重流程。 **禁止使用：** - **agent 不得以任何理由自动加载本 skill**（包括但不限于：AGENTS.md 配置、技能强制评估、上下文推断、检测到 commit 操作）。 - 只做代码调研、diff 查看、问题分析，不准备提交。 ## Repository Rule Discovery 每个仓库先按下面顺序找规则，不要凭经验写死路径： 1. **定位当前机型和版本号**：使用 `model-version-locator` skill 自动发现当前活跃的机型宏和版本号。若已知机型名则传入机型名；否则从当前 git 分支名或上下文推断。输出包含 project 目录、cfg.h 路径、活跃 `#if` 分支和版本宏值。 2. 读取当前目录和上层 `AGENTS.md` / `README` / release 文档。 3. 查找仓库内 release 配置文件，优先级建议： - `.agents/release-config.md` - `.agents/git-commit-standard.md` - `.release-config.md` - 项目自定义说明文件。 4. 以 model-version-locator 的输出作为版本来源基准，然后补充搜索其他可能存在的版本宏：`FIRMWARE_VERSION`、`VERSION_BETA`、`VERSION`、`APP_VERSION`、`BUILD_VERSION`、`RELEASE_VERSION` 等。 4. 搜索产物归档目录：`firmware_record/`、`release/`、`releases/`、`dist/`、`out/`、`bin/` 等。 5. 搜索 changelog/release record（穷举搜索，不得遗漏）： - 根目录及一级子目录下的 `README.txt`、`ReadMe.txt`、`readme.txt`、`CHANGELOG.md`、`RELEASE.md` - `arch/*/change log/`、`arch/*/change_log/`、`arch/**/readme*` 等非标准路径（注意包含空格、大小写变体和多级嵌套） - `docs/release/`、`doc/`、`release-notes/` 等常见子目录 - 必须使用递归 glob（如 `**/readme*`、`**/change*log*/**`），不能只在根目录搜索 确认找到的每个 readme/changelog 文件的完整路径和格式，以便后续更新。 6. 查看历史提交：找最近一次版本递增、固件归档、README/changelog 更新的提交，确认真实格式。 如果规则不明确，先向用户确认；不要默认 fallback 到某个仓库的规则。 ## Repository Config / State File 允许在仓库中维护一个小型配置/状态文件，用来记录跨 commit 的 release 信息。推荐路径：`.agents/release-config.md`。如果仓库已有等价文件，沿用已有文件。 该文件可记录： ```markdown # Release Config ## Version Sources - default: `path/to/version.h`, macros: `FIRMWARE_VERSION`, `VERSION_BETA` - variant-a: `path/to/version.h`, compile macro/env: `<VARIANT_MACRO>`, artifact prefix: `<product-variant>` ## Build Variants | variant | build command | compile macro/env | output artifact | archive dir | archive name pattern | |---|---|---|---|---|---| | default | `<repo build command>` | none | `<out artifact path>` | `<archive dir>` | `<artifact-prefix>_v<version>_<beta>.bin` | ## Changelog - file: `path/to/ReadMe.txt` - insert: top - block separator: `================================================================` - fields: version, date, author, change points ## Release State - last_version_bump_commit: `<commit>` - last_released_version: `<version>` - last_archived_artifacts: - `<path>` ``` 用途：当“多个 commit 才递进一次版本”时，用 `last_version_bump_commit` 或上一个版本记录位置作为汇总边界，不要只拿当前 commit 写 changelog。 ## Modification Basis Hard Gate **硬性门禁：每次执行提交前，必须先向用户询问本次提交的修改依据。此后所有门禁（版本号确认、固件产物、README）方可执行。不存在例外。** ### 执行流程 1. 向用户提问，提供选项的同时允许自定义输入（custom 模式，自由输入）： | 选项 | |---| | 需求变更 | | Bug 修复 | | 性能优化 | | 代码重构 | | 代码审查优化 | | 文档更新 | | 配置变更 | | 测试补充 | | 其他（请在输入中说明） | 2. 若用户在自由输入中填入内容（如工单号、需求编号），以用户输入作为修改依据；否则以用户选择的选项作为修改依据。 3. 修改依据必须写入 commit message 正文中。 4. 不得在未获得用户回复修改依据的情况下继续执行提交流程。 ## Version Bump Rules **硬性门禁：每次加载本 skill 执行提交，必须向用户确认版本号是否递进及递进方式，必须更新固件产物，必须更新 README。不存在例外。** ### 修改版本宏前的预定位 向用户确认版本号递进方式之前，必须先完成以下两层定位，避免改错宏或改错分支： **第一层：定位活跃机型宏块。** 在版本配置文件中搜索机型宏定义（如 `#define TP806L`），确认当前活跃的 `#ifdef`/`#if` 分支区域；只在活跃分支内修改版本号。常见错误：改了非活跃分支的版本宏，版本号未实际生效。 **第二层：区分显示控制宏与真实版本标识宏。** 注意某些宏仅控制 UI 显示（如 `VERSION_BETA 0` 表示自检页不显示 beta 编号），并非真实版本号；真实版本标识宏通常是字符串常量（如 `VERSION_BETA_TEST "v1.0.1"`）。参考 `git log` 确认历史开发者实际修改的是哪个宏。常见错误：把显示控制宏从 0 改成 1，而非修改真实版本字符串。 1. 向用户确认：本次是否递进版本号、递进哪个字段（通常 beta 递增 1）。 2. 递进后重新编译目标变体，生成新版本固件。 3. 将构建产物按历史命名规则复制到归档目录。 4. 汇总变更内容，按仓库模板更新 README/changelog（插入顶部）。 5. 多个变体有不同宏/版本时，分别确认目标变体，不要只改默认分支。 6. 同一版本有多条提交时，changelog 要汇总所有变更，拆为多个 1、2、3 条，不要拆成多条版本记录。 ### 版本号确认门禁 **硬性门禁：所有版本号相关字段确定后、提交前，必须使用 `question` 工具将即将使用的版本号展示给用户确认。未获得用户确认不得提交。** 展示内容必须覆盖版本号出现的所有位置： 1. 使用 `question` 工具，以 select 形式列出即将写入的版本号： - 版本宏值：`VERSION_MAJOR=x VERSION_MINOR=y VERSION_TEST=z`（含 VERSION_BETA 值） - 固件文件命名：`<型号>_Vx.yy.zz_<后缀>`（.bin / .dfu 等） - changelog 版本记录：`版本：<型号>_Vx.yy.zz_<后缀>` - commit message 正文中的版本号 2. 等待用户确认后再继续提交流程。用户选择"确认"才继续，选择"有问题"则返回修正。 3. 此门禁对 commit 和 amend 一视同仁，不可跳过。 ## Changelog / README Rules 写 changelog 前必须确认： - 文件路径和格式来自仓库历史，不要新造格式。 - 插入位置是顶部、底部还是按版本排序。 - 版本字段是否带产物后缀，如 `.bin`。 - 作者字段来自 `git config user.name`，除非仓库规则另有要求。 - 日期格式沿用仓库历史；若仓库没有固定格式，使用 `YYYY.MM.DD`。 生成 changelog 内容时： 1. 找到汇总边界： - 优先使用 `.agents/release-config.md` 中的 `last_version_bump_commit`。 - 否则用上一个 README/changelog 版本记录对应的 commit。 - 再否则询问用户。 2. 汇总边界之后的所有相关 commit。 3. 合并成发布视角的“修改原因 / 修改依据 / 修改方法 / 修改影响”或仓库既有字段。 4. `ReadMe.txt` / changelog 默认写精简版版本摘要，不写详细实现过程；除非用户明确要求详细版，否则一律按发布说明风格输出，而不是设计文档风格。 5. 描述保持短句，优先写关键改动目的、关键方法、关键影响，不展开内部处理逻辑。 6. 每个一级字段下的子项默认不超过 3 点；先压缩语言，再检查是否还能继续合并同类项，避免出现 4 条以上细碎分点。 7. 在不丢失关键信息的前提下，优先合并为更高层级概括表达；能写成一条摘要时，不拆成多条函数级、协议级、状态级细节。 8. “修改方法”只保留必要方法摘要，不写过细实现细节，默认不要写： - 具体函数级处理步骤 - 内部状态机细节 - 输入输出字节级变化 - 调试日志点布置 - 具体兼容分支和兜底路径 9. “修改影响”只保留必要的用户侧/业务侧结果，不写过细技术影响，默认不要写： - 某种旧报文/旧字段/旧格式会被拒绝 - 某个中间态如何切换 - 某个内部 session / payload 如何分段推进 - 过细的协议兼容边界 10. 如果某些细节更适合放设计文档、计划文档、回归文档或代码注释，就不要塞进 `ReadMe.txt`。 11. 推荐摘要表达示例： - 好示例：`收口鉴权入口`、`补充打印阻断`、`完善回归日志点` - 坏示例：逐条罗列函数调用链、协议字段兼容分支、状态切换条件、session/payload 分段推进细节 12. 不要把每个 commit 原文机械粘贴；要按功能归并。 13. 若仓库历史或用户要求“一版本一条”，README/changelog 必须以版本为主键；同一版本内多次修正、回归、补充说明都合并到同一个版本块内，不要拆成多条相同版本记录。 14. README/changelog 总结允许在既有模板条目下继续分点或缩进分层；当同一字段内包含多个独立事项、影响面或风险点时，使用二级分点，不要用长句和分号串联多个主题。 15. 版本履历只写业务结果、行为变化、兼容性、风险和测试维护有意义的信息；不要写流程性负面或后续安排，例如“本次不递进版本号”“不修改版本宏”“不归档固件产物”“后续需要覆盖固件”“已按流程检查”。这些内容只能放在任务汇报或内部执行记录中。 16. 如果本次是非递进版本但有代码改动，也要先检查 README/changelog 是否需要补记录，再判断是否能跳过；不要默认“不升版本=不用同步”。 ## Firmware Artifact Rules 当仓库要求归档固件产物时： 1. 先确认目标变体和构建宏：default / factory / esc / 300dpi / bootloader / product tool 等。 2. 运行仓库真实构建命令生成新产物。 3. **加密变体优先门禁（强制）**：构建完成后，必须先检查构建输出目录产物，再执行后续命名和复制步骤。此门禁不可跳过，不可先归档后补确认。 - **列出构建输出目录产物**：检查是否存在加密变体文件（文件名含 `encrypt`、`enc` 或 `_e` 标记）。 - **若存在加密变体**：必须选择加密版本归档。使用 `question` 工具向用户确认："构建产物包含以下变体：[加密版: `<encrypt_file>` (<size> bytes)] [非加密版: `<plain_file>` (<size> bytes)]，按规则将归档加密版本。" 用户确认后继续；未获确认不得归档。 - **若无加密变体**：使用唯一产物归档，无需确认。 4. 根据版本宏、构建宏和历史命名规则计算归档文件名。 5. 将构建产物复制到对应历史目录。 6. 若同一版本需要多个变体，逐个构建、逐个命名、逐个归档。 7. 归档前确认目标文件是否已存在。若目标文件是当前版本既有归档，且用户或仓库流程要求"更新当前版本产物"，可用最新构建产物覆盖并记录验证证据；若版本/变体/目标文件不明确，或覆盖跨版本、跨变体、历史冻结产物，必须先询问用户。 8. 归档产物应进入 commit，除非仓库规则明确忽略产物。 9. 即使本次不递增版本，只要存在会进入固件镜像的代码或构建输入改动，默认也要构建并更新当前版本对应的固件产物。只有仓库规则、用户明确要求或历史证据明确证明本次没有固件记录要求时，才可不归档；跳过时必须说明证据。禁止用"未递进版本""只是 amend""只是 fix"作为跳过理由。 10. amend 场景下若版本号、版本命名字段、构建宏、产物命名规则、README/changelog 汇总范围或任何构建输入发生变化，必须把当前版本对应的归档产物视为失效，重新构建、重新复制/覆盖归档文件，并把更新后的产物与文档一起纳入 amend。 不要假设所有仓库都把产物放在同一个目录；必须从历史文件和 git log 中确认。 ## Commit Message Rules 提交正文的模板、字段定义、写作风格和正反示例由 `git-commit-template` 定义。使用本 skill 时必须同时遵循 `git-commit-template` 的所有书写规范。关键约束摘要： - 标题聚焦本次提交目的，不把长版本信息塞进标题。 - 正文必须和版本头、README/changelog、归档产物一致。 - 正文只描述本次真实业务、代码、文档、兼容性和影响变化；不要写提交流程、是否递进版本、是否归档固件、后续应该做什么等流程话术。 - 不要把"已按默认流程检查/同步固件和 README/changelog"写成 commit message 的变更点或原因。 ## Operating Pattern 执行 commit 前按顺序处理： 1. 确认用户确实要求提交。 2. **硬性门禁：询问修改依据**（参见 Modification Basis Hard Gate 章节）。未获得用户回复前不得继续。 3. 读取仓库规则：AGENTS、release 配置、历史提交、版本文件、changelog 文件、产物目录。 4. 硬性门禁：若存在任何代码改动（即使未递增版本），按序执行： a. 重新编译目标变体（执行仓库真实构建命令） a2. **加密变体检查**：列出构建输出目录，检测 `*encrypt*`/`*enc*`/`*_e*` 文件。若存在加密变体，执行 Firmware Artifact Rules 第 3 条确认门禁（`question` 工具确认）。 b. 将构建产物按历史命名规则复制到归档目录 c. 验证产物已存在于归档目录中 此门禁对 commit 和 amend 一视同仁，不可跳过、不可推迟到后续步骤。 5. 分别确认本次是否触发版本递增、README/changelog 汇总和固件归档；版本递增不是固件归档的前置条件。 6. 若触发版本递增： - 更新版本源文件。 - 构建目标变体。 - 按历史命名复制/归档产物。 - 汇总当前版本范围内多个 commit 的 changelog 并更新 README/changelog。 - 更新 `.agents/release-config.md` 的 release state（如果仓库采用该文件）。 7. 若未触发版本递增但存在代码改动： - 仍要检查 README/changelog 和固件产物是否需要同步。 - 若代码会进入固件运行镜像，必须先重新构建并更新当前版本对应固件产物。 - 若仓库规则或用户明确不需要记录，才可跳过，并记录证据。 8. 若本次是 amend：存在任何代码改动，或涉及版本号/构建输入/产物命名等变化的，必须重新构建目标变体→复制产物到归档目录→验证归档→重新暂存。不可假设前次 commit 的产物仍然有效。 9. 运行验证：diff check、必要的 LSP/构建/测试、产物存在性和文件名检查。 10. 暂存源码、版本文件、changelog、归档产物、release 配置文件；如果是 amend，必须确认重编译生成的新产物已重新进入暂存区。 11. **版本号确认门禁**：使用 `question` 工具将即将写入的版本号展示给用户确认（参见 Version Bump Rules > 版本号确认门禁）。未获用户确认不得继续。 12. 使用仓库模板创建 commit；commit message 只写实际变更，不写"执行了默认固件/README 同步检查""不递进版本""不归档固件"等流程话术。 13. 提交后验证工作区状态、最新 commit message、Change-Id（若 Gerrit hook 存在）。 ## Common Mistakes - 把“每个 commit”都当成“每次版本递增”。 - 代码有改动却因为没递增版本，就漏掉固件和 README/changelog 同步检查。 - 把“未递进版本”“只是 amend”“只是 fix/中间提交”当作跳过固件产物的理由。 - amend 前改了版本号、版本宏或构建输入，却没有重新编译固件、刷新归档产物并重新暂存。 - 把固件和 README/changelog 同步检查当成“可选项”，等用户提醒才做；正确做法是每次 commit 默认执行。 - 在 commit message 里写“按默认流程检查/同步固件和 README”，造成提交说明噪音；默认流程不要写入提交说明。 - 在 commit message 或版本履历里写“不修改版本宏”“不归档固件产物”“后续需要更新固件”等流程说明。 - changelog 只写当前 commit，漏掉同一版本从上次 release 后累计的多个 commit。 - 同一个版本拆成多条 README/changelog 记录，而用户或仓库规则要求一版本一条。 - 多个独立影响面挤在一条长句里，导致兼容性、密钥策略、payload/session 行为和诊断能力混在一起。 - README/ReadMe.txt 写成设计文档，把函数步骤、协议兼容细节、状态切换或字节级变化塞进版本履历。 - 一级字段下分出 5-8 条碎点，没有先压缩语言、合并同类项。 - README 只写当前提交摘要，没有覆盖整个版本范围内的提交内容。 - 只改版本头，不更新 README/changelog。 - 只构建不归档，或归档文件名仍是临时 `out/` 名称。 - 不看历史目录，把 ESC/300DPI/工厂/boot 产物放到默认固件目录。 - 覆盖已有固件产物而不确认。 - 把某个仓库的路径写死到通用 skill。 - 忘记把 release 配置/状态文件纳入 commit，导致下次无法知道汇总边界。 - 修改版本号时未先定位活跃机型宏块，改到了非活跃分支的宏。 - 混淆显示控制宏与真实版本标识宏，修改了 UI 显示控制宏而非真实版本字符串。 - 搜索 readme/changelog 时只在根目录查找，遗漏 `arch/*/change log/` 等深层嵌套路径。 - 未先询问用户修改依据就直接执行提交流程。 - 版本号确认门禁被跳过，未将最终版本号展示给用户确认就提交，导致版本号写错。 - 构建产出同时存在加密和非加密变体时，未识别加密版本，错误归档了非加密固件。 - 构建产出存在加密变体时，未用 `question` 工具向用户确认加密变体文件名及大小，直接归档（跳过了加密变体优先门禁）。 ## Minimal Checklist 提交前至少确认： - [ ] 已确认用户要求提交。 - [ ] **已向用户询问本次提交的修改依据并获得回复**（Modification Basis Hard Gate）。修改依据已写入 commit message 正文。 - [ ] 已加载本 skill 和 `git-commit-template`（强制依赖）。 - [ ] 已读取仓库 release/commit 规则，而不是套用其它仓库路径。 - [ ] 已分别判断本次是否递增版本、是否更新 README/changelog、是否更新固件产物；未把“不递进版本”作为跳过依据。 - [ ] 若有代码改动，已先重新构建并更新最新固件产物；若跳过，已有用户/规则/历史证据。 - [ ] 若递增版本，已更新版本源、README/changelog、固件归档产物和 release state。 - [ ] 若本次为 amend，凡是涉及版本号、版本宏、构建输入、release 配置或产物命名变化，或存在任何代码改动，均已重新构建、重新归档并重新暂存更新后的固件产物与相关文件。 - [ ] README/changelog 汇总范围正确，覆盖同一版本内多个 commit；若要求一版本一条，已合并到同一版本块，并用二级分点表达独立事项。 - [ ] `ReadMe.txt` / changelog 已按精简版版本摘要写法输出：默认发布说明风格、短句概括、每个一级字段子项默认不超过 3 点，且已合并同类项。 - [ ] `修改方法`、`修改影响` 未写入函数级、协议级、状态级、字节级、session/payload 分段或调试日志布置等过细细节；相关内容已留在更合适的设计/计划/回归/注释位置。 - [ ] README/changelog 和 commit message 未包含“不递进版本”“不修改版本宏”“不归档固件产物”“后续应该”等流程话术。 - [ ] 固件产物文件名、目录和构建宏与历史规则一致。 - [ ] **已执行加密变体门禁**：构建后已检查输出目录产物；存在加密变体时已用 `question` 工具向用户确认加密变体文件名及大小，并选择加密版本归档。 - [ ] **已通过版本号确认门禁**：使用 `question` 工具将版本宏值、固件文件名、changelog 记录和 commit message 中的版本号展示给用户并获得确认。 - [ ] 已运行必要验证并记录结果。 - [ ] commit message 与版本/README/产物一致，且符合 `git-commit-template` 规范。 - [ ] 提交后工作区状态和 Change-Id（如适用）已验证。