From e2b4388ae528fbf15d86c6e25f56c1742a1c3902 Mon Sep 17 00:00:00 2001 From: bootc-dev Bot Date: Fri, 24 Apr 2026 22:06:55 +0000 Subject: [PATCH] Sync common files from infra repository Synchronized from bootc-dev/infra@fb9e91b161adacd1c0e9144a76b64159c482b92e. Signed-off-by: bootc-dev Bot --- .bootc-dev-infra-commit.txt | 2 +- AGENTS.md | 2 +- REVIEW.md | 59 +++++++++++++++++++++++++++---------- 3 files changed, 46 insertions(+), 17 deletions(-) diff --git a/.bootc-dev-infra-commit.txt b/.bootc-dev-infra-commit.txt index 439a61c..0c9344b 100644 --- a/.bootc-dev-infra-commit.txt +++ b/.bootc-dev-infra-commit.txt @@ -1 +1 @@ -56e4f615d38cc4a923f6a7e2a174a0c05a962451 +fb9e91b161adacd1c0e9144a76b64159c482b92e diff --git a/AGENTS.md b/AGENTS.md index 98ff247..fffc7b6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,7 +25,7 @@ include an `Assisted-by: TOOLNAME (MODELNAME)`. For example, ## Code guidelines The [REVIEW.md](REVIEW.md) file describes expectations around -testing, code quality, commit organization, etc. If you're +testing, code quality, commit messages, commit organization, etc. If you're creating a change, it is strongly encouraged after each commit and especially when you think a task is complete to spawn a subagent to perform a review using guidelines (alongside diff --git a/REVIEW.md b/REVIEW.md index 80e6f4d..f9ee4d5 100644 --- a/REVIEW.md +++ b/REVIEW.md @@ -90,24 +90,54 @@ follow your reasoning: "Especially grateful for breaking it up into individual commits so I can more easily follow your train of thought." Preparatory refactoring should be separate from behavioral changes. Each commit -should tell a clear story and be reviewable independently. Commit messages should -explain the "why" not just the "what," and use imperative mood ("Add feature" -not "Added feature"). +should tell a clear story and be reviewable independently. Where applicable, +create "prep" commits that could be merged separately from the behavioral change. -### PR Descriptions +### Commit Messages + +Write clear and descriptive commit messages using a `component: Summary` +subject, such as `kernel: Add find API w/correct hyphen-dash equality, add docs`. +Use imperative mood: "Add integration with..." not "Adds integration with...". + +The body of the commit should start with at least one sentence (or paragraph) +describing **why** the change is being made, even for something apparently +trivial. For example a "refactor" commit might have a "why" rationale of just +"Prep for handling X later." A big commit introducing a feature may seem +self-explanatory, but there is often ambient context like "A large-scale Debian +user wanted this" that provides helpful grounding in the motivation. + +If there's a linked tracking issue, often that will contain a more extensive +rationale that doesn't need to be duplicated entirely in the commit message, +but do ensure the commit message has something useful on its own for a rationale. + +Keep it natural and concise. A few sentences of prose explaining the design +intent or the high-level data flow is often good enough. If there's a +non-obvious consequence of the change, call it out briefly (e.g. "Note the +manifest becomes part of the GC root") rather than explaining the full +mechanism. Think about what a reviewer needs to know that may not be obvious +from a skim of the code. + +Do not restate obvious parts of what is already visible in the commit diff: -PRs should link to the issues they address using `Closes:` or `Fixes:` with -full URLs. One reviewer noted: "I edited this issue just now to have -`Closes: ` but let's try to be sure we're doing that kind of thing in -general in the future." +- "Changed function X to call Y" +- Generic `Changes:` sections with bulleted lists of implementation details +- "Files changed" sections — completely redundant with git -Document known limitations and caveats explicitly. When approaches have tradeoffs -or don't fully solve a problem, say so. For complex investigations, use collapsible -`
` sections to include debugging notes without cluttering the main -description. +Implementation details belong in the code documentation. The goal of the +commit message is like a "cover letter" for the change, with a primary +rationale of why the change is being made, alongside a concise summary of +its implementation. -Think about broader implications: "But we'll have this problem across all repos -right?" Consider how your change affects the wider ecosystem. +Another thing that can go in the commit message is brief descriptions +of alternative approaches that were considered and discarded. + +Closes: tags should generally come at the end of the commit message. + +### PR Descriptions + +Generally, just restate the commit message. + +Where it makes sense, it is OK to include additional details though. ### Keeping PRs Current @@ -123,7 +153,6 @@ Do not add `Signed-off-by` lines automatically—these require explicit human action after review. If code was AI-assisted, include an `Assisted-by:` trailer indicating the tool and model used. - ## Architecture and Design ### Workarounds vs Proper Fixes