Commit formatting

The format of the commit messages in OctoPrint’s repository generally tries to follow the conventional commit spec to make the commit log more uniform and easier to read and skim through, especially during release preparations.

This document describes how this is currently implemented.

Note that not all commits in OctoPrint’s repository are following this format. Merge and revert commits are kept on git’s default formatting to make things easier when using stock tooling, anything prior to June 2024 still uses a different approach, and here and there a different type or scope than those documented gets (mis-)used out of confusion at commit-time.

Also, while contributors are welcome to use this format, it’s not required from them either (and pull requests are usually squashed in any case on merge).

Consider the following more a guideline rather than a rule[1], and a cheat sheet for developers to hopefully make everything more uniform in the future.

General commit

In general, conventionally formatted commits look like the following:

<type>[(<scope>)][!]: <description>

<body>

<references>

<footer>

Non-exhaustive lists of both types and optional scopes can be found below.

An optional ! following the type or type(scope) tag designates a breaking change.

The optional multiline body must be separated from the header line by one empty line. it should describe the commit further, as needed.

Any optional references should be separated from the previous part by one empty line. This is where the GitHub specific linking keywords (e.g. Closes #1234 or Fixes #5678) go.

The optional multiline footer must be separated from the body (or header, if there is no body) by one empty line.

Merge & revert commits

Contrary to the format described above, both merge and revert commits follow the default git format:

Merge branch '<merged branch>' into <merge target>

Revert "<commit message>"

Examples

feat: add achievements plugin

fix(ci): update raspberrypi keyfile to fix canary build

ux: 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 #5267

Merge branch 'bugfix' into dev

Revert "fix(ci): update raspberrypi keyfile to fix canary build"

Types

The following types can be used. This list is non-exhaustive and will be extended as needed.

  • chore: general chores (e.g. version bumps, dependency bumps, release preparations, …)

  • ci: continuous integration related (e.g. workflow adjustments)

  • docs: documentation related changed (includes full blown docs as well as bundled markdown files)

  • dx: developer experience related (e.g. introduction of a new task in the Taskfile, improvement of existing tooling)

  • feat: adding a new feature (e.g. a new bundled plugin, new UI feature, …)

  • fix: bug or security fix

  • meta: updating meta files (e.g. .github/*.yml and similar, minus the workflows, those are covered under ci)

  • refactor: refactoring related, no (intentional) public API changes

  • style: code style related changes (e.g. pre-commit configuration updates and their required code adjustments)

  • test: test related changes (unit tests, e2e tests)

  • wip: commit is part of a work in progress & will likely be squashed later

Scopes

The following scopes can be used. This list is non-exhaustive and will be extended as needed.

  • achievements: bundled achievements plugin

  • api: related to the public REST API

  • backup: bundled backup plugin

  • ci: CI related

  • cli: related to the command line interface

  • coreui: related to the core user interface

  • corewizard: bundled corewizard plugin

  • discovery: bundled discovery plugin

  • docs: documentation related

  • e2e: related to the Playwright based end-to-end tests

  • errortracking: bundled errortracking plugin

  • gcv: bundled gcode viewer plugin

  • health_check: bundled health check plugin

  • plugins: anything plugins related

  • pmgr: bundled plugin manager plugin

  • serial: bundled serial connector plugin

  • settings: settings related

  • storage: related to the internal storage API

  • systeminfo: systeminfo related

  • upmgr: bundled upload manager plugin

  • ux: related to the general user experience