doc: commit_convention: overhaul and formalize unspoken rules (#1717)

Link: https://github.com/nix-community/stylix/pull/1717 Reviewed-by: awwpotato <awwpotato@voidq.com>
2025-07-28 21:40:30 +02:00 · 2025-07-28 21:40:30 +02:00 · 57d036d922
commit 57d036d922
parent 683d626986
1 changed files with 77 additions and 20 deletions
--- a/doc/src/commit_convention.md
+++ b/doc/src/commit_convention.md
@ -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

-| 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.                                     |
+| 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 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.
+The following examples should demonstrate everything:

-The summary should start with a lowercase letter, and should not end with
-punctuation.
+- [`ci: add workflow to label merge conflicts`](
+  https://github.com/nix-community/stylix/commit/46caa4122c4eacafba8e38f4b9344dd149064a10)

-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.
+- [`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
+
+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.