企业官网建设流程全解析

MemOS 提交信息编写完整指南：用 Conventional Commits 写出能过评审与 CI 的提交

【免费下载链接】MemOSSelf-evolving memory OS for LLM & AI Agents: ultra-persistent memory, hybrid-retrieval, and cross-task skill reuse, with 35.24% token savings and DeepSeek Harness support.项目地址: https://gitcode.com/gh_mirrors/memos/MemOS

上周五，一位贡献者向 MemOS 提交了第一次 PR。代码本身没问题，评审意见却是：“提交信息未遵循 Conventional Commits（约定式提交），请重写。”同时，版本发布工具也无法把他的提交自动归类，该版本的 changelog 直接缺了一条记录。MemOS 的官方 commit message 规范 commit_guidelines.md 明确要求：所有提交信息都必须是 Conventional Commits 格式。这篇文章按新手上手顺序，讲清提交信息怎么写才能一次通过评审与 CI。

提交信息怎么写：一张模板搞定格式

CONTRIBUTING.md 与 commit_guidelines.md 在这件事上完全一致：提交信息 = 必填首行 + 可选 body + 可选 footer。

<type>: <short description> [optional body] [optional footer]

首行只有两件事要写：

• type：8 种提交类型之一，紧跟一个冒号，中间不留空格；
• description：这次提交“做了什么”的简短描述。

📌 最容易被忽略的一条规则是祈使语气：用add、fix、update，而不是过去时added、fixed。原因在于首行是拼在 type 后面读的一句指令——feat: add user authentication读起来是“加：加用户认证”，换成added节奏就断了，提交历史也会变得不统一。

大改动的 body 写的是为什么（why），而不是做了什么——diff 本身已经展示了 what changed，body 的价值在于补上动机，比如“为什么这里要用 Redis 后端而不是内存”。footer 用来挂 issue 引用，例如Closes #123。

提交类型怎么选：8 种速查

官方定义的 8 种类型，对应的是“你改了什么”这件事。选类型时先问自己这个问题：

🔍 仍然拿不准时，用最小作用域判断：在feat与refactor之间犹豫，就看“行为变没变”，变了就是feat。

两对最容易混的“双胞胎”辨析

style vs refactor。一句话判定：diff 有没有改变代码的组织方式？没有——只动了空白、缩进、引号——就是style；动了函数提取、文件移动，就是refactor。反例：你既调了缩进，又把重试逻辑抽成了公共函数，却标了style: tidy whitespace——函数抽取是结构重组，应标refactor: extract retry logic into shared helper，或者干脆拆成两个提交各归各的类型。

chore vs ci。一句话判定：改动的文件是否影响 CI 流水线的运行？.github/workflows与 Makefile 里的 CI 任务归ci；pyproject.toml 这类文件里的依赖版本（它同时声明了pre-commit依赖）归chore。反例：你只改了 pyproject.toml 一行依赖版本，却写了ci: update build config——CI 流水线根本不经过这个文件，正确写法是chore: bump dependency versions。

不遵守约定式提交，你会失去什么

把规范当“形式要求”，是最大的误解。没有type前缀，会直接坏掉三件事：

1. changelog 无法自动生成。版本工具依赖feat（新功能）与fix（修复）做归类与版本号决策；首行写“update some code”，工具无处归档，语义化版本组织的变更日志（参考子项目的 CHANGELOG.md）就会缺条目。
2. 评审多一轮返工。CONTRIBUTING.md 的“Good PR”清单把 Conventional commit messages 列为合并前置项之一，且检查不绿 PR 不能合并。不合规的提交信息等于让评审者从 diff 反猜你的意图——多数人不会猜，只会让你重写。
3. 历史不可检索。前缀统一后，git log --grep="^fix:"一行命令筛出全部修复；不合规则每次回顾都要翻全量历史。

走一遍完整流程：从同步上游到提 PR

🧭 提交信息写对了，流程走错照样卡住。development_workflow.md 的完整链路可以一次执行：

git clone https://gitcode.com/gh_mirrors/memos/MemOS cd MemOS make install # 装依赖并设置 pre-commit hooks git checkout dev && git pull git checkout -b feat/your-feature-name # 从 dev 建分支 # ...实现改动，make test 必须全绿后才提 PR git fetch upstream && git rebase upstream/dev git commit -m "feat: add Redis Streams backend for MemScheduler" git push origin feat/your-feature-name

两条硬性要求：

PR 的目标分支必须是上游dev，不是main——提到 main 的 PR 会被要求改目标。

一个 PR 只装一个逻辑改动。“顺手修个无关 bug”就拆成两个分支、两个提交、两个 PR；非平凡改动在 footer 或 PR 描述里关联 issue，如Closes #123。

好坏对照：提交信息最常见的 4 个错误

按下表自查你的 commit message：

表中“修正后”的几条正是 CONTRIBUTING.md 给出的官方示例，与本仓库真实模块对应，如 src/memos/mem_scheduler/、src/memos/mem_cube/，可直接当作模板套用。

提交前过一遍的 5 条自检

• 首行符合<type>: <description>格式，且 type 是 8 种之一？
• description 是祈使语气（add/fix/update，而非 added/fixed）？
• 这次提交是单一逻辑单元，没有混装其他类型？
• 大改动的 body 解释了“为什么”，而不是复述 diff？
• PR 目标分支是dev，测试通过，关联了 issue？

✅ 五条全部勾上，你的提交信息就能同时通过自动化工具链和人工评审。

【免费下载链接】MemOSSelf-evolving memory OS for LLM & AI Agents: ultra-persistent memory, hybrid-retrieval, and cross-task skill reuse, with 35.24% token savings and DeepSeek Harness support.项目地址: https://gitcode.com/gh_mirrors/memos/MemOS