后端前端图像处理人工智能AI 应用【免费下载链接】photoprismAI-Powered Photos App ✨项目地址https://gitcode.com/gh_mirrors/ph/photoprism点击查看免费下载导读本文以 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 submittingfeature-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 清单语法- [ ]每条标准必须清晰、可测试、无歧义每条必须使用以下需求等级关键词之一关键词含义适用场景MUST必须满足否则该 Issue 不算完成核心功能与必要行为SHOULD强烈建议但非严格必需推荐行为、体验优化MAY可选的增强锦上添花的功能示例来自 feature-request.md 模板- [ ] component MUST expected behavior - [ ] component SHOULD expected behavior - [ ] component MAY expected behavior2.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的区分依据是代码原本应当做什么而非工作量大小类型定义典型场景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.ymlFeature 表单强制 User Story、问题陈述、方案、备选方案并将 Acceptance Criteria 设计为带 MUST/SHOULD/MAY 占位符的必填文本域。.github/ISSUE_TEMPLATE/feature-request.mdMarkdown 版模板展示了### Background、### Open Questions、### Acceptance Criteria、### References的完整分节以及- [ ] component MUST/SHOULD/MAY expected behavior的清单写法。.github/PULL_REQUEST_TEMPLATE.mdPR 模板同样要求 Description、Related Issues 与 Acceptance Criteria把实现即验证的原则延伸到合并请求。AGENTS.md仓库代理总则其 Style Notes 章节与commit-and-docs-style.md逐条对应Commit 消息、Issue 类型、User Story、验收清单、Title Case、RFC 3339 时间戳并补充了 Go/JS 代码注释规则、测试覆盖要求与容器/宿主机开发模式约定构成完整的人机协作贡献守则。六、快速自查清单提交任何改动前按以下清单过一遍即可与仓库规范对齐Commit祈使句 单词前缀关联了 Issue/PR 编号≤ 80 字符没有 AI 署名尾注Issue 标题简洁、祈使语气、大写前缀 冒号 空格Bug 标题是否改为陈述故障Issue 描述以**As a role, I want goal, so that outcome.**开头章节用###结尾是 MUST/SHOULD/MAY 验收清单类型按代码本应做什么选择Bug/Enhancement/Feature/Task/Epic半成品选Task文档标题符合 Chicago Title Case美式拼写选项标志在前RFC 3339 UTC 时间戳与合法 ID/UID/UUID 示例specs/公开产物中grep -n specs/无匹配未触碰specs/generated/日期内容变更后刷新了**Last Updated:**这套规范的价值在于让每个 Commit 可扫读、每个 Issue 可验收、每篇文档可预测。对于 PhotoPrism 这类规模庞大、由 AI 辅助开发与社区共建的仓库统一的格式约定就是协作的润滑剂——遵循它你的贡献就能顺畅进入审查、测试与合并流程。赞分享后端前端图像处理人工智能AI 应用【免费下载链接】photoprismAI-Powered Photos App ✨项目地址https://gitcode.com/gh_mirrors/ph/photoprism点击查看免费下载相关推荐Apache Ossie与NVIDIA GSF转换器完全指南3步搞定双向语义模型互转Apache Ossie与NVIDIA GSF转换器完全指南3步搞定双向语义模型互转 Apache Ossie 前身为 Open Semantic Inte后端数据建模数据集成NG-ZORRO 提交信息规范实战指南基于 commit-msg 技能生成 Conventional Commit 消息NG ZORRO 提交信息规范实战指南基于 commit msg 技能生成 Conventional Commit 消息 导读 本文以 NG ZORRO 仓库UI组件前端Qwen Code 白标桌面客户端构建教程一份 brand.json 如何产出 DMG/EXE/AppImage/deb 安装包Qwen Code 白标桌面客户端构建教程一份 brand.json 如何产出 DMG/EXE/AppImage/deb 安装包 Qwen Code 仓库内置人工智能AI Agent代码智能体工具调用交互助手CLIQwen上一篇KMS_VL_ALL_AIO一站式智能激活解决方案彻底告别Windows和Office激活烦恼下一篇iPhone USB网络共享驱动安装实战指南3步解决Windows连接问题创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考