Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Commit convention

Stylix commit messages combine Nixpkgs and Linux Kernel commit conventions:

«SUBSYSTEM»: «SUMMARY»

[«BODY»]

[«BREAKING_CHANGE»]

«CONTEXT_TAGS»

«CONTRIBUTION_TAGS»

where

ElementDescription
«SUBSYSTEM»Area of patched files, optionally nested using : for general subsystems and / for paths.

For example, a patch to /stylix/hm/ should be formatted as stylix/hm instead of stylix: hm, while /stylix/*/palette.nix should be formatted as stylix: palette.

Specific conventions include simplifying modules/«MODULE» to «MODULE», mapping /flake.{lock,nix} and /flake/ to flake, mapping /.github/ to ci, and using treewide for changes that cannot be categorized under a more specific subsystem.
«SUMMARY»Concise, single-line explanation of up to 72 characters, written in the imperative mood, starting lowercase, and not ending with punctuation.
«BODY»Detailed, self-contained explanation of the problem, its user impact, the technical solution, and any optimizations or trade-offs, focusing on one problem per patch.
«BREAKING_CHANGE»Dedicated BREAKING CHANGE: «BODY» section for breaking changes.
«CONTEXT_TAGS»Tags providing external context, such as Closes:, Fixes:, Link:, and Reverts:.
«CONTRIBUTION_TAGS»Contribution tags for crediting contributors and indicating patch reliability, such as Approved-by:, Co-authored-by:, Reviewed-by:, and Tested-by:.

The following examples should demonstrate everything:

note

«SUBSYSTEM» nesting is a recent convention. Consequently, examples are scarce.

Maintainer Notice

When merging, add the PR ID in the commit header as «SUBSYSTEM»: «SUMMARY» (#«PR_ID») and reference the PR with the Link: context tag.

Ensure all appropriate «CONTEXT_TAGS» and «CONTRIBUTION_TAGS» commit tags are added, and include the original or a reworded version of the original commit message or PR description in the final commit message. Do not rely on GitHub to fill in this information.

Use merge commits to preserve valuable commit history, and squash merge otherwise. For example, the «module»: init and «module»: add testbed patchset should be squash merged, while more elaborate patchsets may justify a merge commit. Individual commits within a patchset do not require «CONTEXT_TAGS» and «CONTRIBUTION_TAGS» commit tags, but the merge commit itself must. Ideally, merge commit messages should summarize the patchset's reasoning, similar to Git cover letters, although this is not required.

Automated backport PRs should be rebase-merged to retain the original commit author and leverage the automatically appended (cherry picked from commit «COMMIT_HASH») line.