Pull-Request Documentation in doc/prs
Every pull request (PR) of werkregie has one document in this directory. It documents the change of that PR at that time; later PRs do not maintain it.
Workflow
The steps around a PR document are in docs/agentic-workflow.md, "Steps of a PR".
Naming Convention
YYYY-MM-DD-PR#999-short-description-of-pr.md
- Date of the PR in the format
YYYY-MM-DD, -PR#and the number of the pull request in Gitea,- a short description with dashes between the words,
.md.
Guidelines
- Markdown, in English.
- One sentence per line, to keep diffs readable.
- Explain the why; keep it short.
The Version Line
A line Version: major, Version: minor or Version: patch under the title states how the PR raises the version.
dashboard/build.gradle.kts derives the version from these lines, in the order of the merges (werkregie PR#79).
A document without it raises the patch version; any other value fails the build.
The build reads each document as its merge added it; a later change of the document changes no version.
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.
A paragraph or item that says only "None." (or "Keine.") states that nothing is open and does not count.
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:
- Related Links (optional)
- Problem (required)
- Non-Goals (required)
- Specification (required for features): Gherkin features with their scenarios
- Solution (required)
- Release Notes (optional): what users notice; the build writes them into the changelog
- Open Questions (optional)
- Additional Changes (optional)
- Prerequisite PRs (optional)
- Follow-up PRs (optional)
- Attachments (optional)
For details, see the template. A PR has preferably one Gherkin feature, at most 5 features and 10 scenarios in all; a larger PR gets split.