OctoPrint 提交信息规范：基于 Conventional Commits 的 Commit 格式指南

物联网后端【免费下载链接】OctoPrintOctoPrint is the snappy web interface for your 3D printer!项目地址https://gitcode.com/gh_mirrors/oc/OctoPrint点击查看免费下载本指南以 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 或 PRfooter可选的多行页脚必须与正文若无正文则为标题之间空一行。type与scope的列表均为非穷尽non-exhaustive会随项目需要不断扩充。Merge 与 Revert 提交与上述格式不同merge 提交和 revert 提交遵循 git 的默认格式以便使用标准 git 工具时行为一致Merge branch merged branch into merge targetRevert 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 功能等fixBug 修复或安全修复meta更新元数据文件如.github/*.yml等但workflow 文件除外它们归ci管辖refactor重构相关不有意改变公共 APIstyle代码风格相关改动如 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 APIappkeys内置应用密钥插件auth认证与会话管理backup内置备份插件ccmgr内置自定义控制管理器插件ciCI 相关cli命令行界面相关coreui核心用户界面相关corewizard内置 corewizard 插件discovery内置 discovery 插件docs文档相关e2e基于 Playwright 的端到端测试相关errortracking内置 errortracking 插件eventmgr内置事件管理器插件gcv内置 gcode viewer 插件healthcheck内置健康检查插件i18n翻译文件jsclientJavaScript 客户端库plugins任何与插件相关的内容pmgr内置插件管理器插件printer打印机接口相关serial内置串口连接插件settings设置相关storage内部存储 API 相关swu内置软件更新插件systeminfosysteminfo 相关timelapse内置延时摄影插件tornadoTornado 实现相关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 提交代码、或需要阅读其提交历史来理解演进脉络的开发者本文档都是一份值得收藏的速查表。 相关文档速查完整版本策略见 [docs/development/versioning.rst](https://link.gitcode.com/i/0074aafb0ff39f7e05e611850f14b4ae)分支策略见 [docs/development/branches.rst](https://link.gitcode.com/i/c3de0afc2b39924cfbcf3bde26d0e60c)开发环境搭建见 [docs/development/environment.md](https://link.gitcode.com/i/d858e81d0a81ca2435592b2515032871)贡献流程见 [CONTRIBUTING.md](https://link.gitcode.com/i/bfe2c9b28e94f6bbfdd74f3ea9604914)。赞分享物联网后端【免费下载链接】OctoPrintOctoPrint is the snappy web interface for your 3D printer!项目地址https://gitcode.com/gh_mirrors/oc/OctoPrint点击查看免费下载相关推荐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数据库客户端桌面应用后端前端数据可视化上一篇XLeRobot 3D打印优化终极指南从STL文件到高质量打印件的完整流程下一篇YAYI模型评估指标详解从PPL到BLEU分数创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考