165 lines
7.1 KiB
Markdown
165 lines
7.1 KiB
Markdown
# Compatibility Matrix and Published Claims Decision
|
|
|
|
Status: Superseded
|
|
Cycle: Conformance and compatibility agenda closure pass
|
|
|
|
Superseded by:
|
|
|
|
- `docs/general/specs/13. Conformance Test Specification.md` (Quality-Gate Baseline)
|
|
- `docs/general/specs/17. Compatibility and Evolution Policy.md` (Quality-Gate Baseline)
|
|
|
|
Superseded on: 2026-03-04
|
|
|
|
## 1. Context
|
|
|
|
PBS v1 needed one operational policy for how support claims are published, tested, aged, and retired over time.
|
|
|
|
The open questions from the conformance closure pass, especially Workshop 4, and from `17. Compatibility and Evolution Policy Agenda.md`, Workshop 3 were:
|
|
|
|
- what enters the regression corpus,
|
|
- which compatibility dimensions PBS must publish explicitly,
|
|
- what counts as a published support claim,
|
|
- how claims relate to conformance evidence,
|
|
- and how supported combinations retire without becoming ambiguous.
|
|
|
|
The adopted direction needed to ensure that compatibility tables and support statements are executable commitments rather than prose-only promises.
|
|
|
|
## 2. Decision
|
|
|
|
PBS v1 adopts the following baseline policy:
|
|
|
|
1. Published support claims must be represented by an explicit compatibility matrix.
|
|
2. Every published supported combination must be backed by maintained conformance or regression evidence appropriate to the claim level being published.
|
|
3. The regression corpus is not limited to bug reproductions; it also includes already-published normative examples, accepted behavior claims, and supported matrix combinations.
|
|
4. Unsupported combinations must be stated explicitly rather than inferred from silence.
|
|
5. Claim retirement must be deliberate: when support narrows or ends, the matrix entry, supporting tests, and migration/support note must all change together.
|
|
|
|
## 3. Compatibility Matrix Baseline
|
|
|
|
The minimum PBS compatibility matrix must expose, at minimum, the following dimensions where support is published:
|
|
|
|
1. language line,
|
|
2. stdlib line when reserved stdlib environment selection affects the claim,
|
|
3. runtime line when execution target selection affects the claim,
|
|
4. conformance claim level.
|
|
|
|
The matrix must also expose an explicit support state for each published combination.
|
|
|
|
The minimum support states are:
|
|
|
|
- `supported`
|
|
- `unsupported`
|
|
- `provisional`
|
|
|
|
Meanings:
|
|
|
|
- `supported` means the combination is promised by the publisher and backed by maintained evidence.
|
|
- `unsupported` means the combination is intentionally not promised and tools may reject or decline it without violating the published support policy.
|
|
- `provisional` means the combination is published as incomplete or experimental and must not be confused with ordinary stable support.
|
|
|
|
Silence must not be used where a published matrix exists and a reasonable reader could infer support.
|
|
|
|
## 4. Published Claims and Evidence
|
|
|
|
A published support claim exists whenever a publisher represents, in user-facing or tool-facing form, that a combination or behavior is supported, conforming, or maintained.
|
|
|
|
This includes, at minimum:
|
|
|
|
- a matrix entry marked `supported`,
|
|
- an unqualified or qualified PBS conformance claim,
|
|
- compatibility statements in product or release documentation,
|
|
- and published examples or fixtures presented as normative or supported behavior.
|
|
|
|
Every published claim must map to maintained executable evidence.
|
|
|
|
The evidence may be:
|
|
|
|
- conformance tests,
|
|
- regression tests,
|
|
- or both,
|
|
|
|
provided the evidence covers the claim scope actually being published.
|
|
|
|
`frontend conformance`, `source-runtime conformance`, and `full toolchain conformance` may therefore have different evidence sets, but each published claim still needs evidence inside its own scope.
|
|
|
|
## 5. Regression Corpus Policy
|
|
|
|
The regression corpus must preserve already-published behavior inside the scope of active support claims.
|
|
|
|
At minimum, the regression corpus must include:
|
|
|
|
1. bug reproductions for behavior that was fixed and remains within a supported scope;
|
|
2. published examples that are treated as normative or supported behavior;
|
|
3. accepted conformance claims and the behavior they promise;
|
|
4. supported compatibility-matrix combinations and their required outcomes.
|
|
|
|
The regression corpus may be organized into separate slices by claim level or domain.
|
|
|
|
What matters normatively is:
|
|
|
|
- published supported behavior is regression-protected,
|
|
- evidence remains attributable to the claim it protects,
|
|
- and narrowing support requires deliberate retirement rather than silent drift.
|
|
|
|
## 6. Retirement and Narrowing Policy
|
|
|
|
When a supported combination is retired or narrowed:
|
|
|
|
1. the matrix entry must change explicitly;
|
|
2. the old support state must not remain implied by stale documentation;
|
|
3. the corresponding evidence must be retired, reclassified, or moved to a historical/non-supporting corpus deliberately;
|
|
4. a migration, support-boundary, or rationale note must accompany the change when users could reasonably depend on the retired combination.
|
|
|
|
Retirement does not require one universal changelog format in this decision.
|
|
|
|
It does require that the support boundary become visible and reviewable.
|
|
|
|
## 7. Boundary Between `13` and `17`
|
|
|
|
The adopted split is:
|
|
|
|
- `13. Conformance Test Specification.md` defines the executable evidence obligations: what must enter the conformance or regression corpus and how supported claims become test-backed;
|
|
- `17. Compatibility and Evolution Policy.md` defines the publication policy: which matrix dimensions and support states are required and how supported combinations age or retire.
|
|
|
|
This keeps `13` test-oriented and `17` promise-oriented while ensuring both documents describe the same support contract.
|
|
|
|
## 8. Invariants
|
|
|
|
- Published support claims must be test-backed.
|
|
- A compatibility matrix is normative only when its states have executable meaning.
|
|
- `unsupported` must be explicit when omission would mislead users.
|
|
- `provisional` must not be mistaken for ordinary supported compatibility.
|
|
- Regression protection follows published supported behavior, not only bug history.
|
|
- Narrowing support is a deliberate policy act, not an accidental omission.
|
|
|
|
## 9. Explicit Non-Decisions
|
|
|
|
This decision record does not yet close:
|
|
|
|
- exact compatibility-window lengths by domain,
|
|
- exact migration-tooling triggers,
|
|
- PBX-specific binary compatibility policy,
|
|
- release tooling implementation,
|
|
- or one repository layout for matrix and regression data.
|
|
|
|
## 10. Spec Impact
|
|
|
|
This decision should feed at least:
|
|
|
|
- `docs/general/specs/13. Conformance Test Specification.md`
|
|
- `docs/general/specs/17. Compatibility and Evolution Policy.md`
|
|
|
|
It should also constrain later work in:
|
|
|
|
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
|
|
- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
|
|
- `docs/pbs/agendas/17.4. Compatibility Workshop 4 - Artifact and PBX Compatibility Policy.md`
|
|
|
|
## 11. Validation Notes
|
|
|
|
The intended operational reading is:
|
|
|
|
- if a publisher marks one matrix row as `supported`, there must be maintained evidence for that row;
|
|
- if a combination is no longer supported, the matrix must say so explicitly rather than simply dropping mention of it;
|
|
- and if an example or claim is published as supported behavior, it belongs in the regression story even if it did not originate as a bug report.
|