werkrevisor/docs/prs

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.