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:
Aleksei Sviridkin authored and GitHub committed 2026-11-16 17:31:17 +03:00
commit d205f31017
1 file changed
+2 -2
+2 -2
View File
@@ -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