120 lines
3.5 KiB
Markdown
120 lines
3.5 KiB
Markdown
# 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.
|