add README files to improve documentation organization and structure
This commit is contained in:
@@ -0,0 +1,78 @@
|
||||
# PBS Pull Requests
|
||||
|
||||
This directory contains self-contained PBS change proposals for review.
|
||||
|
||||
## Purpose
|
||||
|
||||
A pull request document packages a proposed change so it can be reviewed as a coherent unit before final integration.
|
||||
|
||||
Use this directory when a change:
|
||||
|
||||
- touches multiple documents,
|
||||
- changes architecture or semantics,
|
||||
- needs explicit review criteria,
|
||||
- or should be assessed before editing the final normative corpus.
|
||||
|
||||
Architecture and decisions come before implementation.
|
||||
|
||||
## Required Properties
|
||||
|
||||
Every pull request document must be self-contained.
|
||||
|
||||
A reviewer should be able to understand the proposal without reconstructing context from chat history or scattered notes.
|
||||
|
||||
## Required Sections
|
||||
|
||||
Each pull request should include, at minimum:
|
||||
|
||||
1. Briefing
|
||||
2. Target
|
||||
3. Method
|
||||
4. Acceptance Criteria
|
||||
5. Tests, when needed
|
||||
|
||||
Recommended additional sections:
|
||||
|
||||
6. Motivation
|
||||
7. Scope
|
||||
8. Non-Goals
|
||||
9. Affected Documents
|
||||
10. Open Questions
|
||||
|
||||
## Section Expectations
|
||||
|
||||
### Briefing
|
||||
|
||||
Summarize the problem and the proposed change in a short, readable form.
|
||||
|
||||
### Target
|
||||
|
||||
State exactly what documents, behaviors, or contracts the proposal changes.
|
||||
|
||||
### Method
|
||||
|
||||
Explain the architectural and editorial approach.
|
||||
If the proposal depends on prior decisions, name them explicitly.
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
List the conditions that must be true for the proposal to be accepted.
|
||||
These should be specific and reviewable.
|
||||
|
||||
### Tests
|
||||
|
||||
Include tests when the change affects executable behavior, conformance, verification, lowering, or observable runtime semantics.
|
||||
|
||||
If tests are not necessary, say why.
|
||||
|
||||
## Writing Rules
|
||||
|
||||
- Keep the proposal self-contained.
|
||||
- Prefer explicit architectural reasoning over implementation detail.
|
||||
- Do not bury acceptance criteria inside prose.
|
||||
- Do not assume unresolved details.
|
||||
- If a required decision is missing, stop and raise the question instead of inferring an answer.
|
||||
|
||||
## Review Rule
|
||||
|
||||
A pull request may propose implementation consequences, but it must not smuggle in unresolved architectural choices as implementation details.
|
||||
Reference in New Issue
Block a user