91 lines
3.1 KiB
Markdown
91 lines
3.1 KiB
Markdown
# PBS Compatibility and Evolution Policy
|
|
|
|
Status: Draft v0 (Skeleton)
|
|
Applies to: compatibility commitments, migration boundaries, deprecation discipline, and evolution constraints across PBS language and related domains
|
|
|
|
## 1. Purpose
|
|
|
|
This document will define the normative compatibility and evolution policy for PBS.
|
|
|
|
## 2. Scope
|
|
|
|
This document is intended to define:
|
|
|
|
- compatibility promises across language, profile, stdlib, and artifact domains,
|
|
- migration boundaries for additive versus incompatible changes,
|
|
- deprecation and removal policy details,
|
|
- behavioral versus binary compatibility expectations,
|
|
- obligations when publishing changes that affect older cartridges or projects.
|
|
|
|
This document does not define:
|
|
|
|
- one repository's release workflow,
|
|
- one implementation's branching strategy,
|
|
- detailed changelog formatting.
|
|
|
|
## 3. Authority and Precedence
|
|
|
|
Normative precedence:
|
|
|
|
1. `1. Language Charter.md`
|
|
2. `2. Governance and Versioning.md`
|
|
3. Runtime and bytecode authority where applicable
|
|
4. This document
|
|
|
|
If a rule here conflicts with higher-precedence authorities, it is invalid.
|
|
|
|
## 4. Normative Inputs
|
|
|
|
This document depends on, at minimum:
|
|
|
|
- `1. Language Charter.md`
|
|
- `2. Governance and Versioning.md`
|
|
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
|
- `7. Cartridge Manifest and Runtime Capabilities Specification.md`
|
|
|
|
## 5. Already-Settled Inputs
|
|
|
|
The following inputs are already fixed elsewhere and must not be contradicted here:
|
|
|
|
- Additive-first evolution is preferred for minor releases.
|
|
- Incompatible changes belong only in major lines with migration guidance.
|
|
- Canonical host primitive versioning uses `(module, name, version)`.
|
|
- Toolchains must reject unsupported targets deterministically.
|
|
- Older supported cartridges are expected to keep running across updates.
|
|
|
|
## 6. Initial Section Targets
|
|
|
|
At minimum, the completed document should contain normative sections for:
|
|
|
|
1. compatibility domains,
|
|
2. behavioral versus binary compatibility,
|
|
3. deprecation windows,
|
|
4. migration obligations,
|
|
5. compatibility-matrix expectations,
|
|
6. artifact and runtime compatibility boundaries.
|
|
|
|
## 7. TODO
|
|
|
|
The following items remain to be closed in future agenda discussion.
|
|
|
|
- Exact compatibility window by domain.
|
|
- Whether PBX/binary compatibility has an independent policy track from source-level compatibility.
|
|
- How stdlib-line compatibility interacts with dependency projects over time.
|
|
- Which changes require migration tooling versus documentation-only migration notes.
|
|
- Whether frontend-only phased implementation claims need distinct compatibility labels.
|
|
|
|
## 8. Non-Goals
|
|
|
|
- Replacing governance with ad hoc decisions.
|
|
- Defining one product release calendar.
|
|
- Freezing every editorial clarification as a compatibility event.
|
|
|
|
## 9. Exit Criteria
|
|
|
|
This document is ready to move beyond skeleton status only when:
|
|
|
|
1. compatibility commitments are explicit by domain,
|
|
2. deprecation and migration duties are normatively described,
|
|
3. source, stdlib, artifact, and runtime compatibility boundaries are separated clearly,
|
|
4. the document no longer relies on unresolved `TODO` items for ordinary v1 compatibility claims.
|