claude-code
4685c8db84
Generated sections (`<!-- generated by … -->` up to the next heading) are no longer checked by the writing rules, and the model and Codex are told to report nothing about them. See docs/prs/. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: #122 Co-authored-by: claude-code <claude-code@javagil.de>
78 lines
3.3 KiB
Markdown
78 lines
3.3 KiB
Markdown
# PR#122: The Reviews Skip Generated Sections of the Docs
|
|
|
|
Version: patch
|
|
|
|
> **WARNING:** This document describes only the change applied in this PR.
|
|
> It may already be outdated once the next PR is merged.
|
|
> Historic PR documentation is not maintained along with new PRs; treat it as a snapshot.
|
|
|
|
## Problem
|
|
|
|
hsadmin-ng fills the `##### Verified by` sections of its PR documents with `tools/generate-verified-by`.
|
|
A generated section starts with the comment `<!-- generated by tools/generate-verified-by -->`
|
|
and ends at the next heading; it has no end marker.
|
|
Its lines hold long links to test sources and scenario reports, up to about 440 characters.
|
|
|
|
The writing rule exempts a long line only if the line is a link and nothing else.
|
|
Lines such as ` using the use-case [X](…)` or `- Scenario-Reports “…”: [Branch](…), [master](…)` hold text besides the links,
|
|
so werkrevisor reports each of them as "line longer than 128 characters".
|
|
The Codex review reports them too: it reads the 128-character rule in the `AGENTS.md` of the repository.
|
|
Nobody can fix such a finding by hand, because the tool overwrites the section.
|
|
|
|
## Non-Goals
|
|
|
|
- No change of `tools/generate-verified-by` in hsadmin-ng.
|
|
- No removal of generated sections from the diff that the model or Codex sees.
|
|
- No configuration of the marker per repository: any `<!-- generated by … -->` comment marks a generated section.
|
|
|
|
## Specification
|
|
|
|
### Feature: the writing rules skip generated sections
|
|
|
|
#### Scenario#122.01: a long line in a generated section is no violation
|
|
|
|
… so that a review reports nothing that only the generator could change.
|
|
|
|
- **Given** a changed PR document with a heading,
|
|
then a comment `<!-- generated by tools/generate-verified-by -->`,
|
|
then a line of 415 characters with text and links
|
|
- **When** werkrevisor checks the writing rules
|
|
- **Then** it reports no violation for that line
|
|
|
|
##### Verified by
|
|
|
|
- [test_writing.GeneratedSectionTest.test_a_long_line_in_a_generated_section_is_no_violation](../../tests/test_writing.py)
|
|
|
|
#### Scenario#122.02: the next heading ends the generated section
|
|
|
|
… so that hand-written text after a generated section is still checked.
|
|
|
|
- **Given** a changed PR document with a generated section,
|
|
then a heading, then a hand-written line of 130 characters
|
|
- **When** werkrevisor checks the writing rules
|
|
- **Then** it reports "line longer than 128 characters" for the hand-written line
|
|
|
|
##### Verified by
|
|
|
|
- [test_writing.GeneratedSectionTest.test_the_next_heading_ends_the_generated_section](../../tests/test_writing.py)
|
|
|
|
## Solution
|
|
|
|
- `werkrevisor/writing.py`: a line that starts with `<!-- generated by` starts a generated section;
|
|
it and all lines up to the next heading are of the kind `generated`, which no writing rule checks.
|
|
- `werkrevisor/codex.py`: the prompt tells Codex to report nothing about a generated section.
|
|
- The `[instructions]` of `.werkrevisor.toml` and of the host configs under `config/` tell the model the same.
|
|
- Version 0.49.1.
|
|
|
|
The change of `.werkrevisor.toml` makes this PR wait for the approval of the human.
|
|
The host configs under `config/` reach the machine configs only with `tools/sync-host-config --apply`.
|
|
|
|
## Open Questions
|
|
|
|
None.
|
|
|
|
## Additional Changes
|
|
|
|
- Werkbaum: `#ops.release` and the two Podman nodes (PR#114, PR#115) are `[^]`;
|
|
since PR#118 each merge is released to mih09.
|