Pull-Request Documentation in docs/prs
Every pull request (PR) of werkdock has one document in this directory;
a pure release PR, with only the version and its section in CHANGELOG.md, needs none.
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
The PR document carries no version line.
The version of werkdock stands in internal/cli/cli.go, and CHANGELOG.md has a section for it;
see "Workflow" in AGENTS.md.
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)
- Open Questions (optional)
- Additional Changes (optional)
- Prerequisite PRs (optional)
- Follow-up PRs (optional)
- Attachments (optional)
What consumers of the CLI notice goes into CHANGELOG.md, not into the PR document.
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.