45 lines
1.9 KiB
Markdown
45 lines
1.9 KiB
Markdown
---
|
|
name: pr-doc
|
|
description: Write or update the pull-request documentation file (PR-doc) under docs/prs/ for the current change. Use when preparing or opening a pull request, when the user asks for a PR-doc, or after finishing a feature that will become a PR — every PR needs one.
|
|
---
|
|
|
|
# Writing a PR-Doc
|
|
|
|
Every pull request needs one documentation file in `docs/prs/`.
|
|
The authoritative convention is `docs/prs/README.md` — read it before writing.
|
|
Copy the section skeleton from `docs/prs/TEAMPLATE.md`.
|
|
|
|
## Filename
|
|
|
|
`YYYY-MM-DD-PR#<number>-short-description-of-pr.md`
|
|
|
|
- Date of the PR, then `-PR#` and the Gitea PR number, then a dash-separated short description, then `.md`.
|
|
- The PR number requires an open pull request; open it early with a `WIP: ` title prefix to reserve the number.
|
|
- If the PR is not opened yet, use `PR#000` as a placeholder in the filename and in scenario IDs, and remind the user to rename both once the number exists.
|
|
|
|
## Structure
|
|
|
|
The main (`##`) sections must appear in exactly this order, omitting sections that do not apply:
|
|
|
|
1. The Problem
|
|
2. Non-Goals
|
|
3. The Scenarios
|
|
4. The Solution
|
|
5. Open Questions
|
|
6. Additional Changes
|
|
7. Prerequisite PRs
|
|
8. Follow-up PRs
|
|
|
|
A `Related Links` section may precede `The Problem`; an `Attachments` section may follow at the very end.
|
|
Do not reorder already-merged PR-docs.
|
|
|
|
## Writing Rules
|
|
|
|
- Keep the snapshot disclaimer blockquote from the template at the top of every PR-doc.
|
|
- English, Markdown, one sentence per line, keep it short.
|
|
- Explain the "why", not just the "what".
|
|
- Scenarios use Markdown-native pseudo-Gherkin (no fenced Gherkin blocks) with IDs `Scenario#<pr-number>.<nn>`.
|
|
- Each scenario gets a `##### Verified by` list linking the tests that cover it (relative links from `docs/prs/`).
|
|
- Mark references to Taiga or other non-public tools as "Hostsharing-internal".
|
|
- PR-docs document the change of that PR at that time; do not maintain historic PR-docs when later PRs change the behavior.
|