-
-
Notifications
You must be signed in to change notification settings - Fork 326
doc: commit_convention: overhaul and formalize unspoken rules #1717
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
0xda157
merged 1 commit into
nix-community:master
from
trueNAHO:doc-commit-convention-overhaul-and-formalize-unspoken-rules
Jul 28, 2025
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,31 +1,88 @@ | ||
| # Commit convention | ||
|
|
||
| To keep things consistent, commit messages should follow a format | ||
| [similar to Nixpkgs](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#commit-conventions): | ||
| Stylix commit messages combine [Nixpkgs]( | ||
| https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#commit-conventions) | ||
| and [Linux Kernel](https://docs.kernel.org/process/submitting-patches.html) | ||
| commit conventions: | ||
|
|
||
| ``` | ||
| «scope»: «summary» | ||
| «SUBSYSTEM»: «SUMMARY» | ||
|
|
||
| «motivation for change» | ||
| [«BODY»] | ||
|
|
||
| [«BREAKING_CHANGE»] | ||
|
|
||
| «CONTEXT_TAGS» | ||
|
|
||
| «CONTRIBUTION_TAGS» | ||
| ``` | ||
|
|
||
| Where the scope is one of: | ||
| where | ||
|
|
||
| | Element | Description | | ||
| |-----------------------|-------------| | ||
| | `«SUBSYSTEM»` | Area of patched files, optionally nested using `:` for general subsystems and `/` for paths.<br><br>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`.<br><br>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: | ||
|
|
||
| - [`ci: add workflow to label merge conflicts`]( | ||
| https://github.com/nix-community/stylix/commit/46caa4122c4eacafba8e38f4b9344dd149064a10) | ||
|
|
||
| - [`flake: infer default.nix import path`]( | ||
| https://github.com/nix-community/stylix/commit/1baa44cf8c3a4699d0beda91f39ba7942b46269d) | ||
|
|
||
| - [`fontconfig: align Home Manager with NixOS and enhance docs`]( | ||
| https://github.com/nix-community/stylix/commit/6d72fc259b6f595f5bcf9634bf2f82b76f939a0d) | ||
|
|
||
| - [`kde: replace systemd unit with AutostartScript for theme application`]( | ||
| https://github.com/nix-community/stylix/commit/e0a41d3a2562ce1b43cad8560333673d04b111b8) | ||
|
|
||
| - [`stylix: do not check lambda pattern names with deadnix`]( | ||
| https://github.com/nix-community/stylix/commit/4add678fe3978177744e8af3c72a6a8a1288227b) | ||
|
|
||
| - [`stylix: rename homeManagerModules to homeModules`]( | ||
| https://github.com/nix-community/stylix/commit/0e5b1613bd9285700c99e5ecf0a4e31da8cb5e04) | ||
|
|
||
| - [`treewide: adjust notification colors to represent urgency`]( | ||
| https://github.com/nix-community/stylix/commit/a6eff346d8e346b5a8e7eb3f8f7c4b36c9597a3c) | ||
|
|
||
| - [`treewide: use mkEnableTargetWith for dynamic autoEnable conditions`]( | ||
| https://github.com/nix-community/stylix/commit/d73d8f6a4834716496bf8930a492b115cc3d7d17) | ||
|
|
||
| - [`wayfire: mixup between wayfire and wf-shell settings`]( | ||
| https://github.com/nix-community/stylix/commit/0150050d6eed373b04fd85e08bd2ae7b5cc8d3b2) | ||
|
|
||
| <!-- | ||
| TODO: Remove this note after 26.05, giving this convention one year of | ||
| establishment. | ||
| --> | ||
| > [!NOTE] | ||
| > `«SUBSYSTEM»` nesting is a recent convention. Consequently, examples are | ||
| > scarce. | ||
|
|
||
| ## Maintainer Notice | ||
|
|
||
| | Scope | Purpose | | ||
| |----------------|------------------------------------------------------------------| | ||
| | `ci` | Changes to GitHub Actions workflows. | | ||
| | `doc` | Changes to the website, `README.md`, and so on. | | ||
| | `flake` | Changes in the `flake` directory, `flake.nix`, and `flake.lock`. | | ||
| | `stylix` | Changes in the `stylix` directory and other global code. | | ||
| | Name of target | Changes to code for a particular target. | | ||
| | `treewide` | Changes across many targets. | | ||
| When merging, add the PR ID in the commit header as `«SUBSYSTEM»: «SUMMARY» | ||
| (#«PR_ID»)` and reference the PR with the `Link:` context tag. | ||
|
|
||
| The scope is meant to indicate which area of the code was changed. Specifying | ||
| the type of change, such as `feat` or `fix`, is not necessary. Dependency | ||
| updates should use whichever scope they are related to. | ||
| 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. | ||
|
|
||
| The summary should start with a lowercase letter, and should not end with | ||
| punctuation. | ||
| 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. | ||
|
|
||
| Most commits to `master` will also include a pull request number in brackets | ||
| after the summary. GitHub adds this automatically when creating a squash merge. | ||
| 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. | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
not sure if this always the best option, currently prs that are merged using a merge commit lose that merge commit on the stable branch which feels somewhat undesirable.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, this has also been bothering me. However, the current Backport action does not retain this information in the generated PR. Feel free to open an issue or submit a PR.