aria-commit
暂无简介
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 1
- Forks
- 0
03 SKILL.md 正文
Git Commit Convention
Subject 说改了什么,正文说为什么。正文默认不写,说明一律英文。
本文件是仓库 commit 说明的规范(技能 aria-commit 的正文),AGENTS.md「Git 提交纪律」节为其摘要,细节以本文件为准。设计目标是一眼读完:多数提交只有一行标题,长内容归 .agents/reference/ 与 .agents/notes/ 等档案文档,commit 只当索引。说明用英文对齐主流规范(Conventional Commits 与 git 社区惯用的祈使句标题),也便于 git log --oneline 在任何终端与编码下稳定显示。本文件自身的中文叙述不受此限。
1. 形状
<type>(<scope>): <subject>
<optional body: 1-3 sentences of prose>
Tests: <optional single line>
| 段 | 必写 | 约束 |
|---|---|---|
| Subject | 是 | 祈使句、动词原形开头(add 不取 added)、小写开头、无句号;软目标 ≤ 50 列。72 列是整行上限(含 <type>(<scope>): 前缀),scope 长时得缩标题 |
| Body | 否 | 只在「标题与 diff 说不清 why」时写;1~3 句散文,≤ 4 行;不分段标签、不列 bullet;72 列折行 |
Tests: 行 |
否 | 跑过测试/构建就带一行结果;纯文档与脚本类可省;须是说明末行 |
语言纪律:说明一律英文且 ASCII-only--禁 CJK、全角标点、Unicode em-dash(破折号语义用 ASCII --);标识符、模块名、指令名原样引用(MAKE_METHOD、ObjString::load_index),不翻译。
2. type 与 scope
| type | 何时用 |
|---|---|
feat |
行为从无到有(新特性 / 新机制 / 新 builtin) |
fix |
行为从错到对 |
refactor |
外部可观测行为不变的结构调整 |
perf |
行为不变,动机就是性能(测量报告按 aria-bench 处理) |
docs |
只改文档与注释 |
test |
只改测试与语料基建(伴随 feat/fix 的测试随本批,不单拆) |
build |
构建系统与依赖 |
style |
不改语义的格式化 |
chore |
其余杂项(.gitignore、脚本、agent 配置) |
scope 取仓库模块名(core / util / value / error / compile / bytecode / runtime / object / memory / tests / docs / build);跨模块逗号分隔、主模块在前、至多三个;全库性改动省略 scope。这是约定而非门禁:check_commit_msg.py 只校验 type 在九类内,不校验 scope。
3. 正文写什么
正文只回答标题与 diff 答不出的两件事:why,以及机制上不显然的那一点(跨文件因果、被否方案的结论)。这两点都写不出来,就不要正文。
禁写内容,判据一句话:这段文字描述的是本次改动,还是得到本次改动的过程--后者删掉,信息无损。
| 类别 | 反例 | 改法 |
|---|---|---|
| 实现步骤流水 | "first added a method to ObjString, then moved it into util" | 只写最终落点 |
| 评审/决策过程 | "(user decision)"、"as discussed, we picked option B" | 直述理由本身 |
| 被否方案推导 | "deliberately not shared with the Lexer parser (which accepts _)" |
一行结论或不写 |
| 实测数据 | "extracting the helper measured 9% slower" | 说明只写原因;配置阈值之类的行为常量可以保留 |
| 文档指针 | "full rationale in some-plan.md" | 删;文档随批提交,git show --stat 即可见 |
| 项目状态叙述 | "there was previously nowhere to put this" | 删;只写现在的行为与机制 |
| 规划词汇 | "M5 phase 3"、"batch 9"、"finalize" | 按语言域名称描述改动 |
| 空泛评价与完成体 | "improve"、"clean up"、"fixed X" | 说机制变化;动词用原形 |
4. 落笔(每次提交强制)
- 暂存后
git diff --cached --stat核范围,只含本批文件。注意git add -u不收未跟踪文件--新增语料/测试/文档要先git add <路径>,否则批次静默残缺且--stat不会提示。 - 说明写进临时文件(如
/tmp/commit_msg.txt),不用-m随手一句。 python3 tools/check_commit_msg.py <file>必须返回 0。两个坑:缺参数时它返 2(不是通过);以Merge/Revert/fixup!/squash!开头时它直接返 0(等于没查)。commit-msg钩子会在落库时再跑一遍,但钩子是本地配置--新环境要先git config core.hooksPath tools/hooks,否则静默不生效。git commit -F <file>;未推送时改说明用git commit --amend -F <file>。git log -1 --format=%B复读一遍。脚本拦截标题和正文格式错误;过程词、百分比、疑似哈希和日期等内容模式只提示。按 §3 复核它们在句中的作用,确认正文确实在解释本次改动的理由。
5. 粒度与流程
一个 commit 一个主题(一个特性 / 一个修复 / 一次重构 / 一轮文档收口),每批独立可编译、可 review、可回滚。与 review 流程咬合:改动完成 → 验证全绿 → 报告并停手 → 用户逐批 review → 点头后落一批 commit,一次 commit = 一次 review 通过的批。main 直推,保持线性历史,避免 merge commit。说明在落库时点当场写,不套用上一批的话术。
6. 例子
style(tests): drop decorative (void) casts
feat(runtime): add string to_int/to_float
Strings could only be converted out, so reading numeric data meant
hand-rolled parsing. Both methods parse the whole string in decimal via
util::parse_int_text/parse_float_text and return nil on failure; to_int
additionally gates the i48 domain.
Tests: ctest all green (default + TagValue); clang-format clean
fix(memory): iterate HashTable benchmark via const_iterator
The benchmark still called for_each_occupied after the slot-scan
primitive was retired, and that target is part of default ALL, so the
default build failed to compile.
反例与改法:
| 反例 | 错在哪 |
|---|---|
20 行 动机: / 改动:(三条 bullet)/ 验证: 三段骨架 |
标签与清单是模板声,改完只剩 2~4 行散文;读者要的是一眼读完 |
| 正文写 "deliberately not shared with the Lexer parser" + "measured 9% slower" + "full rationale in <doc>" | 三段都是「得到本次改动的过程」,对「本批改了哪些代码」零信息 |
| 正文夹 "there was previously nowhere to put this" / "first added a method, then moved it" | 叙述开发进程与实现步骤,读者要的是最终落点与理由 |
| 说明用中文或全角标点 | 与主流规范不一致,且 git log --oneline 在窄终端/异编码下不稳 |
7. 落笔前自检
- [ ] 一批一主题,只含本批文件,type / scope 准确
- [ ] Subject 是英文祈使句、动词原形、无句号、≤ 72 列
- [ ] 正文 ≤ 4 行英文散文(无标签、无 bullet);没有过程叙述、被否推导、实测数字、文档指针、规划词汇
- [ ] 全文 ASCII-only(无 CJK、全角标点、em-dash)
- [ ] 写了
Tests:就确实跑过,且结果与说明一致 - [ ] 已按 §4 五步走过(脚本返回 0),并复读一遍全文
04 同仓库更多 Skills
aria-testing
写 aria 的 C++ GTest 用例或语言语料时使用。核对 CMake 登记、语料位置、期望文件与双配置验收;运行命令见 docs/testing.md,语料判定规则见 tests/language/README.md。
aria-language-change
aria 语言面改动同步清单:改文法(docs/grammar.txt)、词法、语义或新增语言特性时使用。列出全部同步义务面:Parser/CodeGen 实现、tests/language 语料正负向、docs/guide 教程章节、README 特性表、.agents/reference 模块参考,及双配置全量验证要求。
aria-error-messages
aria 报错文案规范速查:写或改任何面向用户的报错文案(编译期 / 运行期 / CLI / ASSERT)时使用。含 detail 通则、句式家族要点、元数族 arity_error 唯一口、被调者泛称、ASSERT 文案规则与机械门禁 tools/check_error_messages.py 的实际覆盖面。规范本体在 .agents/reference/specs/error-messages.md。
aria-bytecode-change
加或改一条字节码指令(OpCode)时使用。列出完整同步面:code.hpp X 表追加与枚举序、dispatch_loop 的 case(漏 case 是运行期 fatal)、opcode_profile 的平行 switch 与 size_of/records_fall_pair、反汇编渲染与 kOpCodeCount 哨兵、CodeGen/CodeUnit 发射侧、instruction-set.md 与 lowering.md、语料与画像。
aria-bench
aria 性能测量纪律:跑基准、做 A/B 对比、写性能报告时使用。含三层分工(bench/lang 进程级墙钟与跨语言对照、lexer/vm/hashtable 进程内微基准、bench/profile 指令频度画像)、各自的构建配方与目录、A/B 对照方法与报告规范、构建旗(ARIA_USE_TAGVALUE / ARIA_USE_MIMALLOC / ARIA_OPCODE_PROFILE)。
aria-add-builtin
给 aria 加内建方法、静态原语或新内建类时使用。列出完整同步面:方法体与方法表、make_class 注册口(实例方法 vs 不绑定的静态原语)、receiver<T> 与 obj_tag 守卫、arity_error 元数口、返回值写槽与 GC 根、语料与文档(含 docs/guide/17-builtin-reference.md)。