discussion framework migration
This commit is contained in:
@@ -0,0 +1,119 @@
|
||||
# PBS Compatibility and Evolution Policy
|
||||
|
||||
Status: Draft v0 (Quality-Gate Baseline)
|
||||
Applies to: practical support states and compatibility publication policy tied to executable quality gates
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This document defines how PBS support is published at the current project stage.
|
||||
|
||||
The policy is intentionally minimal:
|
||||
|
||||
- publish only support claims that are backed by tests,
|
||||
- use a small support-state model that a solo project can maintain,
|
||||
- and avoid over-specifying compatibility promises before backend/runtime contracts settle.
|
||||
|
||||
## 2. Scope
|
||||
|
||||
This document defines:
|
||||
|
||||
- support-state vocabulary for language lines,
|
||||
- minimum published support table fields,
|
||||
- and how support-state changes must be recorded.
|
||||
|
||||
This document does not define:
|
||||
|
||||
- full deprecation-window math per domain,
|
||||
- one binary/PBX compatibility model,
|
||||
- one release process implementation.
|
||||
|
||||
## 3. Authority and Precedence
|
||||
|
||||
Normative precedence:
|
||||
|
||||
1. `1. Language Charter.md`
|
||||
2. `2. Governance and Versioning.md`
|
||||
3. `13. Conformance Test Specification.md`
|
||||
4. This document
|
||||
|
||||
If a rule here conflicts with higher-precedence authorities, it is invalid.
|
||||
|
||||
## 4. Normative Inputs
|
||||
|
||||
This document depends on:
|
||||
|
||||
- `2. Governance and Versioning.md`
|
||||
- `13. Conformance Test Specification.md`
|
||||
|
||||
## 5. Support States
|
||||
|
||||
PBS currently uses three support states:
|
||||
|
||||
- `unsupported`
|
||||
- `experimental`
|
||||
- `supported`
|
||||
|
||||
Meaning:
|
||||
|
||||
- `unsupported`: no compatibility promise.
|
||||
- `experimental`: active development; behavior may change; tests may exist but are not yet a stable support promise.
|
||||
- `supported`: active compatibility promise for declared scope, backed by required quality gates.
|
||||
|
||||
## 6. Gate-Backed Support Rule
|
||||
|
||||
Support states must map to quality-gate evidence:
|
||||
|
||||
1. `frontend-ready` evidence requires Gate U from `13`.
|
||||
2. `integration-ready` evidence requires Gate U plus Gate I when Gate I applies to the language/backend.
|
||||
3. `supported` state requires maintained evidence for the scope being promised.
|
||||
|
||||
No published `supported` claim may exist without mapped test evidence.
|
||||
Unsupported executable surfaces excluded from a claim (for example `SPAWN`/`YIELD` outside `core-v1`) MUST be stated explicitly in published notes.
|
||||
|
||||
## 7. Minimum Published Support Table
|
||||
|
||||
A published support table must include, at minimum:
|
||||
|
||||
1. language identifier,
|
||||
2. language line/version scope,
|
||||
3. runtime line (or `N/A` when Gate I is not applicable yet),
|
||||
4. Gate U status,
|
||||
5. Gate I status (`pass`, `fail`, or `deferred`),
|
||||
6. support state (`unsupported`, `experimental`, `supported`),
|
||||
7. optional notes.
|
||||
|
||||
No additional matrix dimensions are mandatory at this stage.
|
||||
|
||||
## 8. Support-State Changes
|
||||
|
||||
When support changes, the project must update together:
|
||||
|
||||
1. support table state,
|
||||
2. gate evidence status,
|
||||
3. and a short rationale note when users could be affected.
|
||||
|
||||
This document requires visibility of change, not a specific changelog format.
|
||||
|
||||
## 9. Explicit Deferrals
|
||||
|
||||
The following remain intentionally open:
|
||||
|
||||
- domain-specific promise strength beyond the current gate-backed model,
|
||||
- exact deprecation/removal windows,
|
||||
- PBX/binary compatibility policy details,
|
||||
- mandatory migration tooling triggers.
|
||||
|
||||
## 10. Non-Goals
|
||||
|
||||
- Simulating large-organization compatibility governance.
|
||||
- Freezing domains that are still not implemented.
|
||||
- Requiring one matrix tooling format.
|
||||
|
||||
## 11. Exit Criteria
|
||||
|
||||
This document is in a healthy state when:
|
||||
|
||||
1. every active language line has an explicit support state,
|
||||
2. every `supported` state has mapped gate evidence,
|
||||
3. support changes are reflected in table + evidence + note,
|
||||
4. and no compatibility promise depends on undocumented assumptions.
|
||||
Reference in New Issue
Block a user