added PR documentation guidelines and template: introduced docs/prs/README.md and TEAMPLATE.md

2026-07-08 07:03:17 +02:00
parent 0b17537b7c
commit 39fb4e3492
4 changed files with 290 additions and 164 deletions
@@ -0,0 +1,46 @@
+# Pull-Request Documentations in doc/PR
+
+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.
+
+## Naming Convention
+
+`YYYY-MM-DD-PR#999-short-description-of-pr`
+
+1. Date of the PR in the format `YYYY-MM-DD`
+2. followed '-PR#' followed by the number of the pull request in GitEA,
+3. a short description of the PR with dashes between the words,
+4. '.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:
+
+0. Related Links (optional)
+1. The Problem (required)
+2. Non-Goals (required)
+3. The Scenarios (optional for maintenance or bug fixing PRs, 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 [template](TEAMPLATE.md)
@@ -0,0 +1,74 @@
+
+## The Problem
+
+A prosa description of the problem, which this PR is supposed to solve.
+
+## Non-Goals
+
+What this PR deliberately does not do, to delimit the scope.
+
+## The Scenarios
+
+A schematized specification of the requirements, preferably using [Gherkin](https://cucumber.io/docs/gherkin/reference/) vocabulary.
+But Gherkin does not make sense for all kinds of PRs.
+
+Use Markdown-native pseudo-Gherkin instead of fenced Gherkin code blocks.
+This keeps the scenarios linkable and allows direct links to tests, issues, ADRs, or explanations inside the requirement text.
+
+### Feature: headline of the feature
+
+#### Background
+
+- definitions of terms
+- other background information
+
+#### Scenario#236.01: Description of a requirement in the shape of a scenario!
+
+So that ... (describe the goal behind the requirement here).
+
+- **Given** some precondition
+  - **and** another precondition
+- **When** whatever is done
+- **Then** postcondition
+  - **and** another postcondition
+
+##### Verified by
+
+- [ExampleScenarioTests.exampleScenario](../../src/test/java/.../ExampleScenarioTests.java)
+
+#### Scenario#236.02: Description of another requirement in the shape of a scenario!
+
+...
+
+Such feature descriptions are also very helpful in deriving tests and can lead agentic coding AI very well.
+
+## The Solution
+
+Here you describe the changes you made and why you made them, along with reasoning why they were necessary.
+If necessary, you can link to an ADR (Architecture Decision Record).
+Keep it short!
+
+## Open Questions
+
+Here you list decisions which are deliberately left open for the reviewer or a follow-up,
+each with the currently implemented behavior.
+Usually a bullet-list. Keep it short!
+
+## Additional Changes
+
+Here you list any additional changes you made, e.g. "fixed formatting in ..." or "fixed some naming issues".
+Usually a bullet-list. Keep it short!
+
+## Prerequisite PRs
+
+Here you list PRs this PR builds upon.
+
+## Follow-up PRs
+
+Here you list work which is intentionally deferred to later PRs.
+
+## Attachments
+
+Here you can add any longer sections that would interrupt the reading flow in the previous sections.
+Put each attachment on a level-3 heading ('### ...').
+