- 物联网
- 后端
【免费下载链接】OctoPrint
OctoPrint is the snappy web interface for your 3D printer!
本指南以 OctoPrint 仓库的 docs/development/commits.md 为核心，系统梳理其提交信息的标准格式、类型（type）、作用域（scope）与完整示例，并结合仓库内的Taskfile.yml、.git-blame-ignore-revs与CONTRIBUTING.md等佐证，帮助开发者为 OctoPrint 提交代码、阅读提交历史、参与发布准备时快速掌握统一格式，写出一眼可读、便于检索和追溯的 commit message。
背景：为什么 OctoPrint 需要统一的提交格式
OctoPrint 仓库的提交信息在总体上遵循 Conventional Commits（约定式提交）规范，目标是让提交日志更加统一、易于阅读和快速浏览——尤其是在发布（release）准备阶段，维护者需要批量梳理一个版本周期内的所有改动，格式统一的提交日志能极大降低梳理成本。
需要特别说明的是，并非仓库中的每一次提交都严格遵循该格式。文档明确列出了三类例外：
- Merge 与 Revert 提交：保留 git 的默认格式，以便使用标准工具链时操作更方便；
- 2024 年 6 月之前的提交：曾采用另一种基于 emoji 的 gitmoji 方案；
- 个别“误用”：某些提交在提交时由于混淆，使用了文档未列出的 type 或 scope。
同时，OctoPrint并不强制贡献者必须使用该格式——贡献者的 pull request 在合并时通常会被 squash 成单个提交，由维护者统一整理格式。因此，正如文档所强调的：这更像一份“指南”（guideline）而非“规则”（rule），是一张帮助开发者让未来提交更统一的速查表（cheat sheet）。文档作者还风趣地注明：如果这真是硬性规则，仓库里早就应该有一个由 pre-commit 驱动的 linter 了 😉。
这一点在仓库中可以得到印证：OctoPrint 的 Taskfile.yml 中确实存在pre-commit任务（运行pre-commit run --all-files），以及init-dev任务（依次执行task: install-dev、pre-commit install、git config blame.ignoreRevsFile .git-blame-ignore-revs），它们负责代码风格与工具链检查，但并未对提交信息做强制 lint。
通用提交格式（General commit）
约定式提交的 OctoPrint 变体整体结构如下：
<type>[(<scope>)][!]: <description> <body> <references> <footer>各组成部分的要点：
<type>：提交类型，必须从下文给出的类型列表中选择；(<scope>)：可选的作用域，标注本次改动影响的模块，需从作用域列表中选择；!：可选的感叹号，放在type或type(scope)之后，用于标记breaking change（破坏性变更）；<description>：紧随冒号和空格之后的简短描述；<body>：可选的多行正文，与标题行之间必须空一行，用于补充说明提交的具体内容；<references>：可选的引用区，与前一部分之间空一行，放置 GitHub 的链接关键词（如Closes #1234、Fixes #5678），用于将提交关联到对应 issue 或 PR；<footer>：可选的多行页脚，必须与正文（若无正文则为标题）之间空一行。
type与scope的列表均为非穷尽（non-exhaustive），会随项目需要不断扩充。
Merge 与 Revert 提交
与上述格式不同，merge 提交和 revert 提交遵循 git 的默认格式，以便使用标准 git 工具时行为一致：
Merge branch '<merged branch>' into <merge target>Revert "<commit message>"这一约定在当前仓库的实际提交历史中即可观察到：仓库 HEAD 提交即为Merge branch 'next' into dev形式的 merge 提交，符合文档所述“merge 提交保留 git 默认格式”的规则。
完整示例
以下是文档给出的各类提交示例，覆盖了最小化提交、带作用域的提交、带正文/引用/页脚的完整提交，以及 merge、revert 提交：
feat: add achievements pluginfix(ci): update raspberrypi keyfile to fix canary buildux: improve readability of progress bars Bringing back the optics that got lost after merging #4105, now that browsers have more options to make this stuff work. Also introduced a new ko-binding `progressbar` for easier implementation of dynamic progress bars. Closes #5267Merge branch 'bugfix' into devRevert "fix(ci): update raspberrypi keyfile to fix canary build"第三个示例是最典型的“完整形态”提交：标题行ux: improve readability of progress bars之后空一行写正文（解释背景——合并 #4105 后丢失了视觉效果、以及引入的新 Knockout binding），再空一行写入引用Closes #5267自动关闭关联 issue。这个例子同时演示了文档中ux类型与Closes引用关键词的实际用法。
类型（Types）全表
OctoPrint 约定的提交类型如下（列表非穷尽，会按需扩充）：
| 类型 | 适用场景 |
|---|---|
chore | 一般性杂务（如版本号提升、依赖升级、发布准备等） |
ci | 持续集成相关（如 workflow 调整） |
docs | 文档相关改动（包括完整文档与随附的 Markdown 文件） |
dx | 开发者体验相关（如在Taskfile中引入新任务、改进既有工具链） |
feat | 新增功能（如新增内置插件、新的 UI 功能等） |
fix | Bug 修复或安全修复 |
meta | 更新元数据文件（如.github/*.yml等，但workflow 文件除外，它们归ci管辖） |
refactor | 重构相关，不（有意）改变公共 API |
style | 代码风格相关改动（如 pre-commit 配置更新及随之而来的代码调整） |
test | 测试相关改动（单元测试、端到端测试） |
wip | 属于进行中（work in progress）工作的提交，后续大概率会被 squash 合并 |
其中wip类型尤为实用：它明确标识“这是一次尚在进行中的工作提交”，提醒读者和维护者该提交很可能会在后续通过 rebase/squash 被合并进正式提交，不应视为稳定的历史节点。这与 CONTRIBUTING.md 中“PR 理想情况下只包含一个提交（请使用 git 的 rebase 与 squash 功能）”的要求相互呼应。
style与ci、meta的边界值得一提：仓库根目录存在 .git-blame-ignore-revs 文件，其中记录了诸如“Switch to black formatting”“Switch to prettier formatting”“Switch to djlint formatting”等大范围代码风格迁移提交的哈希，供git blame --ignore-revs-file跳过这些噪音提交。这类“由 pre-commit 配置更新引发的全局代码调整”正是style类型提交的典型写照。
作用域（Scopes）全表
OctoPrint 约定的提交作用域如下（列表非穷尽，会按需扩充），每个作用域对应仓库中的一个明确模块：
| 作用域 | 对应模块 |
|---|---|
access | 访问管理相关代码 |
achievements | 内置 achievements 插件 |
analysis | 文件分析相关 |
api | 公共 REST API |
appkeys | 内置应用密钥插件 |
auth | 认证与会话管理 |
backup | 内置备份插件 |
ccmgr | 内置自定义控制管理器插件 |
ci | CI 相关 |
cli | 命令行界面相关 |
coreui | 核心用户界面相关 |
corewizard | 内置 corewizard 插件 |
discovery | 内置 discovery 插件 |
docs | 文档相关 |
e2e | 基于 Playwright 的端到端测试相关 |
errortracking | 内置 errortracking 插件 |
eventmgr | 内置事件管理器插件 |
gcv | 内置 gcode viewer 插件 |
healthcheck | 内置健康检查插件 |
i18n | 翻译文件 |
jsclient | JavaScript 客户端库 |
plugins | 任何与插件相关的内容 |
pmgr | 内置插件管理器插件 |
printer | 打印机接口相关 |
serial | 内置串口连接插件 |
settings | 设置相关 |
storage | 内部存储 API 相关 |
swu | 内置软件更新插件 |
systeminfo | systeminfo 相关 |
timelapse | 内置延时摄影插件 |
tornado | Tornado 实现相关 |
tracking | 内置匿名使用统计插件 |
upmgr | 内置上传管理器插件 |
ux | 通用用户体验相关 |
virtualprinter | 内置虚拟打印机插件 |
将这些作用域与仓库的 src/octoprint/plugins 目录对照可以发现：绝大多数作用域与内置插件一一对应（如achievements、appkeys、backup、ccmgr、discovery、errortracking、gcv、healthcheck、pmgr、serial、swu、timelapse、tracking、upmgr、virtualprinter），另有一部分对应核心子系统的代码目录（如access、api、cli、coreui、printer、settings、storage、tornado），还有一部分对应工程流程（如ci、e2e、i18n、docs、dx、ux）。这意味着读者仅凭提交信息中的 scope 就能快速判断一次改动属于哪个功能模块，无需打开 diff。
结合工程实践：如何在 OctoPrint 开发中应用该格式
1. 与版本管理的关系
提交格式与 OctoPrint 的版本策略是配套使用的：版本号遵循 PEP 440 与语义化版本（MAJOR.MINOR.PATCH），其中 MINOR 版本随新增功能提升、MAJOR 版本在破坏性 API 变更时提升。因此，带!的 breaking change 提交与 MAJOR 版本号提升直接相关；feat类型提交则对应 MINOR 版本提升。统一的提交格式让维护者在发布前可以快速统计某次发布包含了多少feat、多少fix、是否出现!破坏性变更。
2. 与贡献流程的配合
CONTRIBUTING.md 的 "How should I format my commit messages?" 一节直接指向本指南对应章节。贡献者提交 PR 时应遵循的完整流程包括：只针对dev分支提交、一个 PR 对应一个功能/Bug 修复、PR 理想情况下只包含一个提交（使用 rebase/squash）、通过go-task test-unit运行单元测试、通过go-task pre-commit运行 pre-commit 检查套件。由于 PR 合并时通常会被 squash，贡献者个人提交的信息格式虽不强制，但使用统一格式能显著减少维护者在合并整理时的工作量。
3. 与本地工具链的衔接
在 OctoPrint 检出目录中运行go-task init-dev即可一次性完成：安装开发依赖（python -m pip install -e ".[develop,plugins,docs]"）、激活 pre-commit 钩子（pre-commit install）并配置git blame忽略文件（git config blame.ignoreRevsFile .git-blame-ignore-revs）。其中 pre-commit 负责代码风格检查，而提交信息格式则依赖开发者自觉遵循本指南——这正是文档把自身定位为“guideline 而非 rule”的工程现实。
总结
OctoPrint 的提交信息规范可以浓缩为以下几点：
- 主格式：
<type>[(<scope>)][!]: <description>，可选正文、引用区与页脚，各部分之间以空行分隔； - 例外格式：merge 与 revert 提交保留 git 默认格式，2024 年 6 月前的历史提交使用 gitmoji 风格；
- 类型与作用域：11 个类型 + 35 个作用域，均非穷尽、按需扩充，覆盖从核心代码到内置插件、从 CI 到 i18n 的全部仓库模块；
- 定位：面向贡献者与维护者的“指南/速查表”，非强制规则，但能让提交日志在发布准备时更易于阅读、筛选与追溯。
对于任何希望为 OctoPrint 提交代码、或需要阅读其提交历史来理解演进脉络的开发者，本文档都是一份值得收藏的速查表。
- 物联网
- 后端
【免费下载链接】OctoPrint
OctoPrint is the snappy web interface for your 3D printer!
相关推荐
RedisInsight 提交信息规范实战：基于 Conventional Commits 的 Commit Message 编写指南
RedisInsight 提交信息规范实战：基于 Conventional Commits 的 Commit Message 编写指南 本文以 RedisIns
数据库客户端桌面应用后端前端数据可视化3步掌握HeidiSQL：从零开始的高效数据库管理指南
3步掌握HeidiSQL：从零开始的高效数据库管理指南 HeidiSQL是一款功能强大的开源数据库管理工具，支持MySQL、MariaDB、PostgreSQL
即时通讯后端微服务WebSocketRedisInsight 提交信息规范：基于 Conventional Commits 编写高质量 commit message 的完整指南
RedisInsight 提交信息规范：基于 Conventional Commits 编写高质量 commit message 的完整指南 本文以 Redis
数据库客户端桌面应用后端前端数据可视化
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
