From c43fdd6cf6abbdf00ee38e2c69a4ce839aa1b609 Mon Sep 17 00:00:00 2001 From: Tyler Baker Date: Thu, 4 Jun 2026 02:00:00 +0200 Subject: [PATCH 1/2] AGENTS.md: document the enforced commit conventions Going back over the last year of reviews, several conventions that the maintainers enforce are not written down here. Add them alongside the existing commit-message guidance: the Signed-off-by identity must match the author and be a real, routable address rather than a GitHub web-editor noreply; subjects use a lowercase component prefix rather than Conventional Commits or kernel-tree prefixes; branches are rebased on master rather than merged; and added patch files carry an Upstream-Status header. Writing these down keeps commits consistent and is the groundwork for enforcing the deterministic subset automatically later on. Signed-off-by: Tyler Baker --- AGENTS.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 661988747..4217333f3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -161,10 +161,30 @@ Signed-off-by: $(git config user.name) <$(git config user.email)> Never fabricate a name or email; always read from `git config`. +The `Signed-off-by` identity must match the commit author, and must be a real, +routable identity: + +- The author email must appear in a `Signed-off-by` trailer on the same commit. +- Do not author commits through the GitHub web editor: it produces numbered + `NNNN+user@users.noreply.github.com` addresses and arbitrary display names, + which are rejected. Configure `git config user.name`/`user.email` locally and + commit from a checkout. +- Write the trailer as `Signed-off-by: Name ` with a space before `<`. +- `Signed-off-by`, `Acked-by`, `Reviewed-by` and similar trailers for anyone + other than you must reflect approvals that were actually given. This cannot + be verified automatically and is left to maintainer review; do not fabricate + a review or sign-off trail. + Guidelines: - Keep subject line short and specific; capture intent, not a file-by-file dump. - Use imperative mood (`Add`, `Update`, `Drop`, `Enable`, `Revert`). +- Prefix scoped changes with `component: summary` (note the space after the + colon). +- Do not use Conventional Commits prefixes (`feat:`, `fix(scope):`, `chore:`); + follow the OE commit policy and the `component: summary` style above. +- Do not use kernel-tree subject prefixes (`FROMLIST:`, `UPSTREAM:`, + `BACKPORT:`, `FROMGIT:`). - Add a body for non-trivial changes explaining **why** and key design decisions. - Wrap body lines for readability (~72 chars). - Use consistent recipe bump wording for version updates, e.g. @@ -174,3 +194,8 @@ Guidelines: - Each patch must be logically coherent, self-contained, and independently buildable. - The tree must remain in a functional state after every commit. - Fixups within the same patch series are not allowed; changes should be corrected in the patch where they are introduced. +- Rebase your branch on upstream `master`; do not merge `master` into it. Merge + commits in a pull request are rejected. +- Every patch file added under a recipe must carry an `Upstream-Status:` header + with a valid value (`Submitted`, `Backport`, `Pending`, `Inappropriate`, + `Denied`, `Accepted`). From 2b91af9714da136d4e44392257601dab3fde0e2d Mon Sep 17 00:00:00 2001 From: Tyler Baker Date: Wed, 10 Jun 2026 09:30:37 -0400 Subject: [PATCH 2/2] AGENTS.md: add commit authoring recommendations The rules above list what is rejected, but do not give a human a short set of recommendations for writing a good commit and series. Add one: keep each commit atomic, start the message with the problem being solved, keep a valid Signed-off-by chain, add your own sign-off when you pick or apply someone else's commit, and use git cherry-pick -x for backports. Signed-off-by: Tyler Baker --- AGENTS.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 4217333f3..d5f5057f3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -199,3 +199,20 @@ Guidelines: - Every patch file added under a recipe must carry an `Upstream-Status:` header with a valid value (`Submitted`, `Backport`, `Pending`, `Inappropriate`, `Denied`, `Accepted`). + +### Authoring commits + +Beyond the rules above, these make a series easier to review: + +- Keep each commit atomic: one self-contained logical change, so a regression + can be pinned to it with `git bisect` and reverted on its own. If the + subject needs an "and also" (`Foo, and while we are at it, bar and baz`), it + should have been more than one commit. +- Start the commit message with the problem or issue being solved, then + explain the change and why it is the right fix, not just restate the diff. +- Keep a valid `Signed-off-by` chain. Sign off with `git commit -s`, which takes + the trailer from `git config`. +- When you pick or apply a commit written by someone else, keep their authorship + and add your own sign-off with `-s`. +- Backport with `git cherry-pick -x` so the message records the upstream commit + it came from.