114 lines
3.8 KiB
Markdown
114 lines
3.8 KiB
Markdown
# PBS Compatibility and Evolution Policy Agenda
|
|
|
|
Status: Active
|
|
|
|
## Purpose
|
|
|
|
Drive the closure of `17. Compatibility and Evolution Policy.md` so PBS can make explicit promises before implementation and release claims expand.
|
|
|
|
## Context
|
|
|
|
The current skeleton identifies the right policy areas, but it still leaves open:
|
|
|
|
- compatibility domains and windows,
|
|
- the separation between source, stdlib, artifact, and runtime compatibility,
|
|
- deprecation and removal duties,
|
|
- migration-tooling versus documentation-only obligations,
|
|
- and whether phased implementation claims need distinct compatibility labels.
|
|
|
|
This agenda should produce a policy that is strict enough to protect users and toolchains, while still allowing deliberate evolution.
|
|
|
|
## Decisions To Produce
|
|
|
|
1. Decide the compatibility domains PBS speaks about normatively.
|
|
2. Decide the compatibility promise and window for each domain.
|
|
3. Decide the deprecation and removal policy for source, stdlib, and artifact surfaces.
|
|
4. Decide when migration tooling is mandatory versus when written guidance is enough.
|
|
5. Decide whether phased implementation or conformance claims need distinct compatibility labels.
|
|
|
|
## Core Questions
|
|
|
|
1. What exact promise is made to old source code, published cartridges, stdlib consumers, and emitted artifacts?
|
|
2. Is PBX compatibility governed independently from source compatibility?
|
|
3. How do stdlib-line changes affect downstream dependency projects over time?
|
|
4. Which incompatible changes require migration tooling rather than only release notes?
|
|
5. How are compatibility claims constrained by conformance level and runtime line?
|
|
|
|
## Proposed Workshop Sequence
|
|
|
|
### Workshop 1: Compatibility Domains and Promise Levels
|
|
|
|
Purpose:
|
|
|
|
- define the domains PBS makes compatibility promises about,
|
|
- and decide the strength of each promise.
|
|
|
|
Expected decisions:
|
|
|
|
- source, stdlib, cartridge, artifact, and runtime domain boundaries,
|
|
- and behavioral versus binary compatibility split.
|
|
|
|
### Workshop 2: Deprecation, Removal, and Migration Duties
|
|
|
|
Purpose:
|
|
|
|
- close the lifecycle policy for changes that affect published users.
|
|
|
|
Expected decisions:
|
|
|
|
- deprecation windows,
|
|
- removal preconditions,
|
|
- and migration tooling versus documentation-only obligations.
|
|
|
|
### Workshop 3: Compatibility Matrices and Published Claims
|
|
|
|
Purpose:
|
|
|
|
- decide how compatibility claims are expressed across language line, stdlib line, runtime line, and conformance level.
|
|
|
|
Expected decisions:
|
|
|
|
- matrix shape,
|
|
- supported-line expectations,
|
|
- and alignment with `13`.
|
|
|
|
### Workshop 4: Artifact and PBX Compatibility Policy
|
|
|
|
Purpose:
|
|
|
|
- decide whether artifact compatibility has an independent policy track from source compatibility.
|
|
|
|
Expected decisions:
|
|
|
|
- PBX compatibility promise,
|
|
- runtime-loading compatibility boundaries,
|
|
- and obligations when the artifact line changes.
|
|
|
|
## Expected Spec Material
|
|
|
|
The resulting spec work should be able to add or close sections for:
|
|
|
|
- compatibility domains,
|
|
- compatibility windows and support lines,
|
|
- behavioral versus binary compatibility,
|
|
- deprecation and removal discipline,
|
|
- migration obligations,
|
|
- compatibility matrices across language, stdlib, and runtime lines,
|
|
- and labeling rules for partial or staged implementation claims.
|
|
|
|
## Non-Goals
|
|
|
|
- Defining one release calendar.
|
|
- Replacing governance with case-by-case exceptions.
|
|
- Treating every editorial clarification as a compatibility event.
|
|
- Designing product marketing labels.
|
|
|
|
## Inputs
|
|
|
|
- `docs/pbs/specs/1. Language Charter.md`
|
|
- `docs/pbs/specs/2. Governance and Versioning.md`
|
|
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
|
- `docs/pbs/specs/7. Cartridge Manifest and Runtime Capabilities Specification.md`
|
|
- `docs/pbs/specs/13. Conformance Test Specification.md`
|
|
- `docs/pbs/specs/17. Compatibility and Evolution Policy.md`
|