# Pull-Request Documentation in docs/prs

Every pull request (PR) of werkrevisor has one document in this directory.
It documents the change of that PR at that time; later PRs do not maintain it.

## Workflow

1. A new branch gets its PR document right away, and the branch is pushed.
2. A PR is opened with the prefix `WIP: ` in its title; the file name gets the real PR number.
3. The PR keeps the `WIP: ` prefix until its author considers it ready for review.
4. Removing the prefix starts the review by werkrevisor itself, through Werkator.

## Naming Convention

`YYYY-MM-DD-PR#999-short-description-of-pr.md`

1. Date of the PR in the format `YYYY-MM-DD`,
2. `-PR#` and the number of the pull request in Gitea,
3. a short description with dashes between the words,
4. `.md`.

## Guidelines

- Markdown, in English.
- One sentence per line, to keep diffs readable.
- Explain the why; keep it short.
- Mark references to non-public tools as "Hostsharing-internal".

## Open Questions Block the Review

werkrevisor checks the section "Open Questions" of every PR document a PR adds or changes.
An item with `[ ]`, or an item or paragraph without a checkbox, makes the review RED, before any model call.
Mark an answered question with `[x]`; put the answer on an indented continuation line of the item.
The whole item counts as checked, not its source lines.

## Structure

The main (`##`) sections appear in this order; omit the ones that do not apply:

0. Related Links (optional)
1. The Problem (required)
2. Non-Goals (required)
3. The Scenarios (required for features)
4. The Solution (required)
5. Open Questions (optional)
6. Additional Changes (optional)
7. Prerequisite PRs (optional)
8. Follow-up PRs (optional)
9. Attachments (optional)

For details, see the [template](TEMPLATE.md).