• 后端
• 前端
• 图像处理
• 人工智能
• AI 应用

导读

本文以 PhotoPrism 仓库的.claude/rules/commit-and-docs-style.md规范文件为核心，系统讲解该开源项目在Commit 消息、GitHub Issue、文档写作三个维度的统一约定：从 80 字符以内的祈使句提交格式，到以 User Story 开头、以 MUST/SHOULD/MAY 验收清单收尾的 Issue 结构，再到 Chicago 风格 Title Case 与美式英语的文档规范。读完本文，你将掌握一套可直接套用的"可合并、可追溯、可验收"的贡献标准，无论是向 PhotoPrism 提交代码，还是参与其他 Go/Vue 大型仓库协作，都能照此实践。

一、Commit 消息：一句话说清"改了什么"

1.1 句式与前缀

PhotoPrism 要求 Commit 消息使用简洁的祈使句主语（concise, imperative subjects），并以一个单词的前缀（one-word prefix）标注改动所属的领域或主题：

Config: Add tests for "darktable-cli" path detection

前缀即领域词，如Config、Docker、Search、PWA、Faces等。这种"前缀 + 冒号 + 祈使句"的结构让git log在扫视时即可按模块过滤，也便于自动生成变更摘要。

1.2 关联 Issue 或 PR 编号

如果该提交与具体 Issue 或 Pull Request 相关，需要在消息中引用其编号：

Docker: Use two stage build to reduce image size #123 #5632

编号紧跟在标题之后，供维护者在 GitHub 上快速跳转对应讨论。

1.3 硬性限制：80 字符

Commit 消息不得超过 80 个字符。这条限制（配合 72/80 字符的行业惯例）保证消息在终端、git log --oneline、代码托管平台界面上都不会被截断。

1.4 禁止 AI 署名尾注

规范明确规定：不得在 Commit 消息中添加Co-Authored-By: Claude …或其他任何 AI 作者署名尾注（AI-authorship trailer）。这与 AGENTS.md 中"Do not addCo-Authored-Byor any other AI-authorship trailer"的说明一致，目的有二：一是保持提交历史的署名真实可信，二是避免污染 Git 历史元数据。即使提交内容由 AI 辅助生成，也应保持人类作者负责制的提交形式。

二、GitHub Issue：从标题到验收清单的完整结构

2.1 标题：祈使句 + 大写前缀

Issue 标题必须满足三点：

• 简洁（concise）
• 使用祈使语气（imperative mood）
• 以单个大写前缀 + 冒号 + 空格开头

示例：

Search: Add filter for RAW image formats

而Bug 标题的写法相反——它陈述"什么不工作"（states what does not work），而不是祈使句：

PWA: Unable to download or share files

仓库模板中已经内置了这种前缀风格：.github/ISSUE_TEMPLATE/bug_report.yml 的默认标题为Bug: Edit the title before submitting，feature-request.yml 为Feature: Edit the title before submitting，提交者只需替换冒号后的内容。

2.2 描述：User Story 开场

每条 Issue 描述必须以一句 User Story 开头，格式为：

**As a <role>, I want <goal>, so that <outcome>.**

即"作为某个角色，我想要某个目标，以便获得某个结果"。这是需求沟通的最小闭环：它同时回答了"谁"、"要什么"、"为什么值得做"三个问题。feature-request.yml 与 feature-request.md 都将该句式作为必填项，并明确要求"Feature requests MUST begin with a one sentence user story"。

2.3 正文分节：统一使用三级标题

Issue 描述中的章节统一使用level-3 Markdown 标题（###），例如### Acceptance Criteria。feature-request.md 模板给出了推荐的章节组合：

• ### Background—— 解决什么问题、为什么对大量用户有价值
• ### Additional Context—— 补充截图与背景
• ### Open Questions—— 待澄清的开放问题
• ### Acceptance Criteria—— 验收标准

在 User Story 之后，需要依次给出预期行为摘要（summary of the expected behavior）、设计理由（rationale）、技术考量（technical considerations）与约束（constraints），让评审者无需追问即可理解方案的来龙去脉。

2.4 验收标准：MUST / SHOULD / MAY 语义化清单

描述必须以Acceptance Criteria（验收标准）检查清单结尾，规则如下：

• 使用 GitHub 清单语法：- [ ]
• 每条标准必须清晰、可测试、无歧义
• 每条必须使用以下需求等级关键词之一：

示例（来自 feature-request.md 模板）：

- [ ] <component> MUST <expected behavior> - [ ] <component> SHOULD <expected behavior> - [ ] <component> MAY <expected behavior>

2.5 清单的维护纪律

• 及时勾选：当某条标准的实现完成并经过验证后，将其标记为- [x]；未验证、未实现或跳过的MAY增强项保持- [ ]不勾。
• 完成判定：一个 Issue 只有在所有MUST项都被勾选时才视为完成；绝不允许仅凭计划或未运行的测试就勾选（never tick a box on the strength of a plan alone or an unrun test）。
• 联动更新：当某个提交满足了一部分标准时，先在对应的检查框上更新，再引用该 Issue。
• 代理边界：Agent 只有在用户明确要求时，才能创建、编辑、关闭、重新打开、改标签或修改 GitHub Issue。

这套"测试驱动验收"的理念在 Pull Request 模板中同样可见：.github/PULL_REQUEST_TEMPLATE.md 要求包含自动化单元/验收测试、SQLite 3 与 MariaDB 10.5.12+ 的数据库兼容性验证、Chrome/Safari/Firefox 响应式测试等验收项。

三、Issue 类型：按"代码本应做什么"分类

3.1 类型体系与查询方式

本仓库的 Issue 模板使用 GitHub 的type:属性，而不是bug/idea标签。类型是在组织层面配置的，不在仓库内，因此规范建议用以下命令读取，而不是凭空假设：

gh api orgs/photoprism/issue-types --jq '.[].name'

截至 2026 年 9 月，可用类型为Task、Bug、Feature、Enhancement和Epic。提交流程同样可用 CLI 完成，无需打开 Web 界面：

gh issue create --type <name> # 提交时设置类型 gh issue edit --type <name> # 事后修改类型

3.2 四种类型的判别标准

Bug、Enhancement、Feature、Task的区分依据是代码原本应当做什么，而非工作量大小：

3.3 标题即快速判别法

规范给出了一个高效的判题技巧：标题本身就是测试。

• 如果标题读起来天然像一个失败描述（如Faces: Slow recognition after a correction），它就是Bug；
• 如果标题读起来天然像祈使句，它就不是Bug。

确定类型后，标题措辞要与类型匹配——Bug 陈述故障，其余类型陈述期望行为。

3.4 半成品机制：选Task而非Bug

一个常见的误判场景：某个机制"接了一半线"——辅助函数已存在、代码意图可辨，但没有任何调用方。这不是Bug，因为没有任何功能发生回归；它只是从未被完成。此时应选择Task，而不是把意图争论成缺陷。

Epic则是跟踪型 Issue，保持开启状态，直到其下所有子 Issue 全部关闭。

四、文档与规范：可预测的排版与用词

4.1 产品名与拼写

• 文档中产品名一律写作PhotoPrism。
• 所有文档、标题、Issue 与 PR 文本、Commit 消息使用美式英语：behavior、color、labeled、license、analyze、normalize、optimize，而不是英式的-our/-ise/-re/-lled变体。
• 代码片段、标识符、文件路径、引用的第三方许可名称等按原样保留，不做改写。

4.2 Chicago 风格 Title Case（标题大小写）

文档标题采用Chicago 风格标题大小写（Chicago-style title case），并带有代码与路径感知的规范化规则：

• 大写：首词、冒号/破折号/句末标点后的第一个词、所有主要词（含连字符复合词的第二部分）。
• 小写：仅限三个字母及以下的冠词、短连词、短介词，且不处于上述位置时。
• 保留缩略词大写：如 API、CLI、HTTP、JSON，以及斜杠分隔的缩略词组（如 CSV/TSV）。
• 保留规范关键词大写：以规范语义使用的 RFC 2119 / RFC 8174 关键词（MUST、SHOULD、MAY、SHALL、REQUIRED、RECOMMENDED、OPTIONAL）保持大写。若标题中偶然使用了这类词导致大小写混杂（如What You must Not），应改写措辞（如What You Do Not），而不是手工修大小写——因为下一次格式化运行会撤销手工修改。
• 保留行内代码原样：行内代码（`foo`）、文件路径（如docs/foo-bar.md）、斜杠命令（如/grill-me）内容不做大小写重排。
• 标题中表示并列关系时，用&而非And/Or。

4.3 命令行示例与时间戳

• 书写 CLI 示例或脚本时，选项标志放在位置参数之前（除非命令本身要求其他顺序）。
• 请求与响应示例中使用RFC 3339 UTC 时间戳；文档与测试中使用合法（valid）的 ID、UID 和 UUID 示例，保证示例可直接复制验证。

4.4specs/嵌套仓库的访问边界

• 嵌套的specs/子仓库不一定存在于每个克隆环境中；不要在主仓库添加依赖specs/路径的Makefile目标。
• 自动生成的配置与命令参考位于specs/generated/下，Agent 不得读取、分析或修改其中的任何内容。
• 严禁在公开产物中引用specs/路径——包括 Issue 正文、PR 描述、包 README（如frontend/README.md、internal/*/README.md）、顶层CODEMAP.md/GLOSSARY.md、specs/之外的代码注释。外部读者会看到 404，且会泄露私有子仓库的存在。唯一的例外是AGENTS.md和CLAUDE.md中的提示。保存任何面向公众的文件前，可用此命令快速自检：

grep -n "specs/" <file>

若存在匹配行，说明仍有遗漏。

4.5 文档维护：刷新日期

每次修改文档内容后，需刷新文档顶部的**Last Updated:**日期，格式如January 20, 2026（不带时间）；仅做格式或空白类编辑时保持不变。仓库根目录的 AGENTS.md 即为实例，其头部标注**Last Updated:** September 27, 2026，且全文与本文规范保持一致——实际上，.claude/rules/commit-and-docs-style.md与AGENTS.md的 Style Notes 章节互为印证，后者是前者在仓库层面的总纲。

五、在仓库中的落地：模板与配套规则

上述规范并非纸上谈兵，仓库中已有一整套可用的工程化支撑：

• .github/ISSUE_TEMPLATE/bug_report.yml：结构化的 Bug 表单，内置type: Bug、默认标题、必填的"What is not working as documented?"、复现步骤、软件版本、设备信息、网络环境（反向代理/防火墙/VPN/CDN）等字段，把 2.1-2.2 节的规范固化为表单校验。
• .github/ISSUE_TEMPLATE/feature-request.yml：Feature 表单，强制 User Story、问题陈述、方案、备选方案，并将 Acceptance Criteria 设计为带 MUST/SHOULD/MAY 占位符的必填文本域。
• .github/ISSUE_TEMPLATE/feature-request.md：Markdown 版模板，展示了### Background、### Open Questions、### Acceptance Criteria、### References的完整分节，以及- [ ] <component> MUST/SHOULD/MAY <expected behavior>的清单写法。
• .github/PULL_REQUEST_TEMPLATE.md：PR 模板同样要求 Description、Related Issues 与 Acceptance Criteria，把"实现即验证"的原则延伸到合并请求。
• AGENTS.md：仓库代理总则，其 Style Notes 章节与commit-and-docs-style.md逐条对应（Commit 消息、Issue 类型、User Story、验收清单、Title Case、RFC 3339 时间戳），并补充了 Go/JS 代码注释规则、测试覆盖要求与容器/宿主机开发模式约定，构成完整的"人机协作贡献守则"。

六、快速自查清单

提交任何改动前，按以下清单过一遍，即可与仓库规范对齐：

1. Commit：祈使句 + 单词前缀？关联了 Issue/PR 编号？≤ 80 字符？没有 AI 署名尾注？
2. Issue 标题：简洁、祈使语气、大写前缀 + 冒号 + 空格；Bug 标题是否改为陈述故障？
3. Issue 描述：以**As a <role>, I want <goal>, so that <outcome>.**开头；章节用###；结尾是 MUST/SHOULD/MAY 验收清单？
4. 类型：按"代码本应做什么"选择Bug/Enhancement/Feature/Task/Epic；半成品选Task？
5. 文档：标题符合 Chicago Title Case？美式拼写？选项标志在前？RFC 3339 UTC 时间戳与合法 ID/UID/UUID 示例？
6. specs/：公开产物中grep -n "specs/"无匹配；未触碰specs/generated/？
7. 日期：内容变更后刷新了**Last Updated:**？

这套规范的价值在于：让每个 Commit 可扫读、每个 Issue 可验收、每篇文档可预测。对于 PhotoPrism 这类规模庞大、由 AI 辅助开发与社区共建的仓库，统一的格式约定就是协作的润滑剂——遵循它，你的贡献就能顺畅进入审查、测试与合并流程。

• 后端
• 前端
• 图像处理
• 人工智能
• AI 应用