79 lines
2.0 KiB
Markdown
79 lines
2.0 KiB
Markdown
# 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.
|