This directory contains documentation for each pull request (PR).
IMPORTANT: The PR-documentation documents the change which was applied in that PR.
Such documentation might be outdated right after the next PR was merged.
Historic PR-documentation is not maintained along with new PRs.
When a PR needs no documentation
A pure release PR — the version bump and its release-notes entry, no code — needs none.
Every other PR carries a version bump and a release-notes entry of its own as well: patch for a fix, minor for new behaviour.
The release notes are the documentation of that PR, and the change itself is documented by the PR it ships.
Every other PR needs one.
Naming Convention
YYYY-MM-DD-PR#999-short-description-of-pr
Date of the PR in the format YYYY-MM-DD
followed '-PR#' followed by the number of the pull request in GitEA,
a short description of the PR with dashes between the words,
'.md'
Yes, to get the PR-number, you need to open a pull request first,
but initially prefix its title with WIP: to mark it as a work in progress until it is ready for review.
Guidelines
Documentations must be written in Markdown format.
Use Englisch, it's a public open source project.
Use clear and concise language and keep it short.
Include relevant details and context, explain the "why".
Mark reference to Taiga or any other tool that is not public as "Hostsharing-internal".
If necessary, copy important parts of the ticket description.
One sentence or statement per line to make diffs easier to read.
Structure
The main (##) sections have to appear in exactly this order, omitting sections which do not apply:
Related Links (optional)
Problem (required)
Non-Goals (required)
Specification (optional for maintenance or bug fixing PRs, required for features)
Solution (required)
Open Questions (optional)
Additional Changes (optional)
Prerequisite PRs (optional)
Follow-up PRs (optional)
Attachments (optional)
For details, see template.
A PR has preferably one Gherkin feature, at most 5 features and 10 scenarios in all; a larger PR gets split.
The workflow around the document is in docs/agentic-workflow.md.
