# 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.