mirror of
https://github.com/cozystack/cozystack.git
synced 2026-11-21 12:13:55 +09:00
docs(agents): reword the section-banner comment rule (#5336)
## What this PR does Rewords the comment rule in `docs/agents/contributing.md` that rejects "section banners", so it describes the content it objects to instead of a formatting style. The rule exists to reject a comment that only names the code below it and adds nothing, such as a heading over a `ClusterRole` whose `kind` and `name` already say what it is. "Banners a section" reads instead as an objection to decoration, and it gets applied to the shape: ```yaml # == addresses view cluster role == <- rejected as a banner # addresses view cluster role <- passes, though it says exactly as little apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata: name: cozy:addresses:view ``` The reverse also happens: a heading that does orient the reader in a long file can be rejected for its `==`. Precedent in the tree shows how unevenly the rule lands. `packages/system/backup-controller/templates/tenant-clusterroles.yaml` and `packages/system/migration-controller/templates/tenant-clusterroles.yaml` open their roles with `# == … ==` lines, and the rule only ever catches new code. The phrase changes in both places it appears: - **In-code comments** blocker: "banners a section" becomes "merely names the section below it". - **Undisclosed machine authorship** tells: "section banners" becomes "comments that merely name the section below them". What the rules enforce is unchanged. The same comments are still rejected; the wording just points a reviewer at the missing substance rather than at the decoration. ### Screenshots Not a UI change. ### Downstream repositories - [x] No downstream repository is affected by this change - [ ] [cozystack/website](https://github.com/cozystack/website) - follow-up: - [ ] [cozystack/terraform-provider-cozystack](https://github.com/cozystack/terraform-provider-cozystack) - follow-up: - [ ] [cozystack/ansible-cozystack](https://github.com/cozystack/ansible-cozystack) - follow-up: - [ ] [cozystack/ccp](https://github.com/cozystack/ccp) - follow-up: - [ ] [cozystack/talm](https://github.com/cozystack/talm) - follow-up: - [ ] [cozystack/cozyhr](https://github.com/cozystack/cozyhr) - follow-up: - [ ] [cozystack/cozy-proxy](https://github.com/cozystack/cozy-proxy) - follow-up: - [ ] [cozystack/cozystack-telemetry-server](https://github.com/cozystack/cozystack-telemetry-server) - follow-up: - [ ] [cozystack/external-apps-example](https://github.com/cozystack/external-apps-example) - follow-up: - [ ] [cozystack/examples](https://github.com/cozystack/examples) - follow-up: - [ ] [cozystack/community](https://github.com/cozystack/community) - follow-up: The trigger map's entries for this file, in cozystack/ccp and cozystack/community, cover the commit convention, which this PR does not touch. Neither repository restates the comment rules. ### Release note ```release-note docs(agents): the comment rule against section banners now names what it rejects, a comment that merely names the section below it, rather than the banner formatting. ``` <!-- This is an auto-generated comment: release notes by coderabbit.ai --> <!-- coderabbit-ai-generated:v1 --> ## Summary by CodeRabbit * **Documentation** * Updated review-blocker guidance to clarify that comments merely naming the section below them qualify as blockers, including in the examples. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
This commit is contained in:
1 file changed
+2
-2
@@ -104,8 +104,8 @@ Each item below is decided by the text alone, and each one on its own makes a re
|
||||
|
||||
- **Commit message.** Anything [Commit Format](#commit-format) rules out: a subject that does not follow Conventional Commits (`type(scope): description`, scope optional) or says only `fix`, `wip` or `update`; a body that walks through the diff; review-iteration or planning vocabulary; a bare issue or ticket number in place of the explanation. A missing `Signed-off-by` trailer (DCO) blocks too.
|
||||
- **Trailers.** The rule is in [AI Agent Attribution](#ai-agent-attribution). Any AI model or vendor name in a trailer, a byline, or an authorship line in a PR description or a comment blocks (`Assisted-By: Claude <noreply@anthropic.com>`, `Co-authored-by: <model> <noreply@...>`, `Generated-by:`, a `Generated with <tool>` line). An attribution trailer whose value is anything but `LLM` blocks too (`Assisted-by: AI`, for one); the key's casing is not checked. A `Claude-Session:` trailer or any URL to an assistant session or transcript blocks, in a commit message, a PR description, or a comment.
|
||||
- **In-code comments.** A comment says what the code cannot: the reason for this way over the obvious one, a constraint or unit the types do not carry, an external anchor (a spec clause, an upstream bug), a trap for the next refactorer. Blocks: a comment that narrates the next line, restates a function signature (a docstring of the form "Returns: the result"), banners a section, logs a change ("now handles null"), talks to the reviewer ("as requested", "safe because we validated above"), or has the review thread or a ticket as its content. Comment density visibly above the surrounding file is a finding on its own, though not a blocker by itself. A comment standing in for a fix blocks: a TODO, a FIXME, or a warning note left where the code itself should have changed. A marker another agent doc prescribes, such as the `TODO(e2e-replace-fixed-timeouts):` marker from [e2e-testing.md](./e2e-testing.md), is a declared carve-out, not a fix by comment.
|
||||
- **Undisclosed machine authorship.** Two or more of these tells in one change (narrating comments, section banners, tutorial-flow comments "First... Next... Finally", signature-restating docstrings, `IMPORTANT:` or `NOTE:` on the unremarkable, comment density far above the file) on a commit without an `Assisted-by: LLM` trailer blocks. The tells are findings on their own, trailer or not.
|
||||
- **In-code comments.** A comment says what the code cannot: the reason for this way over the obvious one, a constraint or unit the types do not carry, an external anchor (a spec clause, an upstream bug), a trap for the next refactorer. Blocks: a comment that narrates the next line, restates a function signature (a docstring of the form "Returns: the result"), merely names the section below it, logs a change ("now handles null"), talks to the reviewer ("as requested", "safe because we validated above"), or has the review thread or a ticket as its content. Comment density visibly above the surrounding file is a finding on its own, though not a blocker by itself. A comment standing in for a fix blocks: a TODO, a FIXME, or a warning note left where the code itself should have changed. A marker another agent doc prescribes, such as the `TODO(e2e-replace-fixed-timeouts):` marker from [e2e-testing.md](./e2e-testing.md), is a declared carve-out, not a fix by comment.
|
||||
- **Undisclosed machine authorship.** Two or more of these tells in one change (narrating comments, comments that merely name the section below them, tutorial-flow comments "First... Next... Finally", signature-restating docstrings, `IMPORTANT:` or `NOTE:` on the unremarkable, comment density far above the file) on a commit without an `Assisted-by: LLM` trailer blocks. The tells are findings on their own, trailer or not.
|
||||
|
||||
## PR Title Auto-Labeling
|
||||
|
||||
|
||||
Reference in new issue
Block a user