74 lines
3.0 KiB
Markdown
74 lines
3.0 KiB
Markdown
# PR#72: Hints on PR Documents Are Line Comments Again
|
|
|
|
> **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.
|
|
|
|
## Related Links
|
|
|
|
- [PR#66](https://git.javagil.de/mi/werkrevisor/pulls/66): hints on documentation stay in the result comment.
|
|
- [werkator PR#145](https://git.javagil.de/mi/werkator/pulls/145): corrects the PR document of werkator PR#141.
|
|
|
|
## The Problem
|
|
|
|
Since 0.31.0, a hint on a file of the category `docs` stands only in the result comment and holds no merge.
|
|
In the 20 PRs since then, 6 findings stood only in the result comment:
|
|
|
|
| PR | Finding | File | Rating |
|
|
|---|---|---|---|
|
|
| werkrevisor #68 | a count in the Werkbaum is wrong | Werkbaum | real, reached main |
|
|
| werkator #141 | "fails at once", but the test waits five seconds | PR document | real, reached main |
|
|
| werkrevisor #70 (2 findings) | Given/When/Then, implementation details | PR document | real, Jev's YELLOW had them too |
|
|
| werkator #132 | a scenario narrates the mechanism | PR document | style |
|
|
| werkator #133 | "as" reads awkwardly | PR document | style |
|
|
|
|
Both real errors that reached main were statements about the PR, one of them in a PR document.
|
|
The PR document is what the human reviewer reads first, and what a later reader takes as the record of the PR.
|
|
|
|
## Non-Goals
|
|
|
|
- No change for hints on other documentation: README, guides and the Werkbaum keep the behaviour of PR#66.
|
|
- No change to `hint_min` or to the verdicts.
|
|
|
|
## The Scenarios
|
|
|
|
### Feature: a hint on a PR document gets an answer
|
|
|
|
#### Scenario#72.01: a hint on a PR document is a line comment
|
|
|
|
So that a wrong statement about the PR is answered before the merge.
|
|
|
|
- **Given** a GREEN review with automerge
|
|
- **And** its only finding is a hint on a file of `[pr_doc] globs`
|
|
- **When** werkrevisor publishes the review
|
|
- **Then** the hint is a line comment that holds the merge
|
|
|
|
##### Verified by
|
|
|
|
- [test_doc_hints.DocHintsTest.test_a_hint_on_a_pr_document_is_a_line_comment](../../tests/test_doc_hints.py)
|
|
|
|
#### Scenario#72.02: a hint on other documentation stays in the result comment
|
|
|
|
So that the rounds saved by PR#66 stay saved.
|
|
|
|
- **Given** a GREEN review with automerge
|
|
- **And** its only finding is a hint on a README or guide, not on a PR document
|
|
- **When** werkrevisor publishes the review
|
|
- **Then** the hint stands only in the result comment
|
|
- **And** the merge is scheduled
|
|
|
|
##### Verified by
|
|
|
|
- [test_doc_hints.DocHintsTest.test_a_hint_on_documentation_is_no_line_comment](../../tests/test_doc_hints.py)
|
|
|
|
## The Solution
|
|
|
|
- A GREEN finding on a file of `[pr_doc] globs` is a line comment again; other documentation keeps PR#66.
|
|
- `tools/review-rounds` lists, per PR since a date, the review rounds, their verdicts, the line comments
|
|
and the findings that stood only in the result comment; it gave the table above.
|
|
- Version 0.31.6.
|
|
|
|
## Follow-up PRs
|
|
|
|
- Run `tools/review-rounds` again after the next 10 to 15 PRs and check the effect of 0.31.x and of this PR.
|