企业官网建设流程全解析

• 数据库
• 灾备

本篇指南完整讲解 Databasus 开源仓库的 Git 提交与分支命名约定：FEATURE/FIX/REFACTOR三种 subject 前缀、禁止!破坏性标记的原因、body 要点式写法、feature/<scope>分支命名规则，以及这些约定如何与仓库 CI 的自动化语义化版本（SemVer）发布流程联动。读完你不仅能写出符合仓库规范的提交，还能理解为什么在 subject 中写一个!会让发布流程直接触发 major 版本升级。

该规范定义在仓库的 git-commits skill（面向 Agent 的编码技能文档）中，且被 CI 发布工作流 的determine-version任务直接消费，是仓库工程化体系的一部分。

一、为什么要为提交信息立规矩

Databasus 是一个 PostgreSQL 备份工具（附带 Point-In-Time-Recovery 与恢复验证能力），仓库由 Go 后端、TypeScript 前端、Next.js 官网、验证 Agent 等多个子工程组成，开发以 Agent 与人工协作进行。在这种仓库中，提交信息不仅仅是变更日志，还是发布流程的输入：CI 会根据上一次 Git tag 之后所有提交的 subject 前缀，自动判断下一个版本应该 bump minor、patch 还是 major。

正因如此，SKILL.md 对提交格式做了强约束，并在文件头的 metadata 中写明其适用场景："Write Databasus commit messages and branch names using the repository's release-compatible format. Use when creating, editing or reviewing a commit message or branch name in this repository."——即创建、编辑或审查本仓库的提交信息与分支名时，都必须使用这套与发布流程兼容的格式。

二、subject 格式：三种前缀，别无他选

提交信息的 subject（首行）必须使用以下三种格式之一：

FEATURE (scope): Summary FIX (scope): Summary REFACTOR (scope): Summary

要点解析：

• 前缀大写：FEATURE、FIX、REFACTOR必须保持这种精确写法。这不是随意风格选择——CI 的正则匹配是大小写敏感的（见下文第四节）。
• scope 括号与冒号：(scope):中 scope 用于标示影响面，例如(postgresql)、(backups)、(frontend)。冒号后跟一句话摘要（Summary）。
• 禁止使用!：subject 中任何位置都不能出现!字符。原文档明确警告："Never use!anywhere in the subject. The release workflow treats it as a breaking change and triggers a major version bump."（切勿在 subject 的任何位置使用!。发布工作流会将其视为破坏性变更并触发 major 版本升级。）

如果某个变更本质上是破坏性的，正确的表达方式是把它写进 OpenSpec 文档（见第四节），而不是在提交信息里使用!标记。

三、body 写作规范：短 bullet list，不要长叙事

提交信息的正文（body）部分有明确的风格约束：

• 用简短的 bullet list 列出变更点，每条一行；
• 不要写长篇叙事段落；
• 不要硬性在 80 字符处换行（Do not hard-wrap lines at 80 characters），这与其他许多仓库的习惯相反，需要注意。

原文档给出的 body 示例：

- validate PostgreSQL targets and quote conninfo values - verify workspace access before applying saved credentials - isolate local sockets and rotate internal database credentials - add regression coverage and OpenSpec documentation

可以看到，每条 body 都是"动词短语 + 变更对象"的精简句式，覆盖了功能变更、安全加固、测试与文档补充等多个维度，信息密度高且易于浏览。

四、理由与实现细节放 OpenSpec，且随实现一起提交

规范明确要求："Keep the reasons and implementation details in OpenSpec. When a change has related OpenSpec files, commit them together with the implementation."（把理由和实现细节放在 OpenSpec 中。当变更有关联的 OpenSpec 文件时，将它们与实现一起提交。）

也就是说，提交信息只承担"变更摘要"的角色，而"为什么这么改、具体怎么实现"这类信息沉淀在 OpenSpec 变更文档中。仓库的 openspec/changes 目录保存了这类变更记录，例如已归档的2026-09-21-add-email-two-factor-auth变更就包含：

openspec/changes/archive/2026-09-21-add-email-two-factor-auth/ ├── proposal.md # 变更动机、依赖、影响面、范围外事项 ├── design.md # 技术设计 ├── tasks.md # 任务分解 └── specs/ └── two-factor-authentication/ └── spec.md # 最终规格

当一次提交既包含实现代码又包含上述 OpenSpec 文件时，应把两者放在同一个提交里，保持"变更 + 文档"的原子性。

五、分支命名：与 subject 前缀一一对应

分支名使用与提交前缀一致的词根：

feature/<scope> fix/<scope> refactor/<scope>

例如实现某个新功能时开feature/backups-retention，修复缺陷时开fix/s3-upload-retry。分支名的 scope 可以与后续提交信息中的 scope 保持一致，便于在合并时快速对映。

六、不要随意添加 co-author 归属

规范明确：除非用户直接要求，否则不要在提交信息中添加 co-author 归属（"Do not include co-author attribution unless the user requests it directly."）。在 Agent 协作开发中这条规则尤为关键，避免每次提交自动带上无关的署名。

七、为什么!会导致 major 版本升级：发布工作流源码印证

SKILL.md 中"!触发 major 版本升级"的警告并非空穴来风，它对应着 CI 发布工作流 中determine-version任务（on: push到main且提交信息不含[skip-release]时运行）的版本判断逻辑。

该任务使用git describe --tags --abbrev=0取得最近 tag 作为当前版本（无 tag 时回退为v0.0.0），然后遍历两次 tag 之间的全部非 merge 提交的 subject，核心判断逻辑如下：

HAS_FEATURE=false HAS_FIX=false HAS_BREAKING=false while IFS= read -r commit; do if [[ "$commit" =~ ^FEATURE ]]; then HAS_FEATURE=true elif [[ "$commit" =~ ^FIX ]]; then HAS_FIX=true elif [[ "$commit" =~ ^REFACTOR ]]; then HAS_FIX=true # refactor 按 patch 处理 fi if [[ "$commit" =~ BREAKING[[:space:]]CHANGE ]] || [[ "$commit" =~ "!" ]]; then HAS_BREAKING=true fi done < <(printf '%s\n' "$COMMITS") if [ "$HAS_BREAKING" = true ]; then BUMP_TYPE="major" elif [ "$HAS_FEATURE" = true ]; then BUMP_TYPE="minor" elif [ "$HAS_FIX" = true ]; then BUMP_TYPE="patch" else BUMP_TYPE="none" fi

从这段代码可以得出几条与 SKILL.md 直接对应的硬事实：

1. !是破坏性变更触发器：正则[[ "$commit" =~ "!" ]]会在 subject 中匹配到任何!字符时把HAS_BREAKING置为 true，进而把BUMP_TYPE定为major。这就是 SKILL.md 禁止在 subject 中出现!的根本原因——一个手滑的!就会让下一次发布从 patch/minor 直接变成 major。
2. FEATURE触发 minor 升级：只要两次发布之间出现任何以FEATURE开头的提交，版本就 bump minor（npx semver -i minor）。
3. FIX与REFACTOR触发 patch 升级：FIX和REFACTOR都会置HAS_FIX=true，版本 bump patch。
4. 没有任何匹配前缀时不下发：BUMP_TYPE=none，should_release=false，CI 不会触发镜像发布。

因此，提交前缀不仅影响变更日志的可读性，还直接决定 Databasus 镜像的版本号走势。遵循FEATURE (scope):/FIX (scope):/REFACTOR (scope):格式，等于让发布版本号自动、准确地反映每次合并的内容。

八、快速参考：一次合规提交的完整流程

结合以上规范，一次符合 Databasus 仓库约定的提交可以这样完成：

1. 开分支：按变更类型选择feature/<scope>、fix/<scope>或refactor/<scope>；
2. 写 subject：FEATURE (backups): add retention policy presets（前缀大写、带 scope 括号、无!）；
3. 写 body：2~5 条精简 bullet list，不写长段落、不硬换行到 80 字符；
4. 同步 OpenSpec：如果仓库中已有对应变更记录（如 openspec/changes 下的 proposal/design/tasks/spec），把相关 OpenSpec 文件与实现代码放在同一提交中；
5. 署名：除非用户明确要求，不添加 co-author 归属；
6. 提交并推送：CI 会在合并到main后依据 subject 前缀自动计算下一个版本号，无需手工维护版本号。

如需更深入了解配套工程化约定，可继续阅读仓库根目录的 AGENTS.md 与 CI 发布工作流；其他 Agent 编码技能（如 OpenSpec 的 propose、update、archive 流程）位于 .agents/skills 目录下，可与本提交规范配合使用。

• 数据库
• 灾备