95 lines
2.7 KiB
Markdown
95 lines
2.7 KiB
Markdown
# PBS Compatibility Workshop 2
|
|
|
|
Status: Active
|
|
|
|
## Purpose
|
|
|
|
Run the second focused discussion for `17. Compatibility and Evolution Policy.md` on lifecycle discipline:
|
|
|
|
- deprecation,
|
|
- removal,
|
|
- migration duties,
|
|
- and when tooling is mandatory versus documentation-only guidance.
|
|
|
|
## Why This Slice Second
|
|
|
|
This slice follows domain definition because the right deprecation and migration policy depends on what kind of surface is changing.
|
|
|
|
## Proposed Meeting Order
|
|
|
|
1. Reconfirm the compatibility domains and promise strengths from Workshop 1.
|
|
2. Close deprecation requirements by domain.
|
|
3. Close removal preconditions.
|
|
4. Close migration-tooling versus documentation obligations.
|
|
5. Record matrix consequences for Workshop 3.
|
|
|
|
## Decisions To Produce
|
|
|
|
1. Deprecation windows by domain.
|
|
2. Removal preconditions by domain.
|
|
3. Migration-tooling obligations.
|
|
4. The policy for changes that are incompatible but still deliberate.
|
|
|
|
## Candidate Decisions
|
|
|
|
### 1. Deprecation Must Precede Removal For User-Facing Stable Surfaces
|
|
|
|
Candidate direction:
|
|
|
|
- source and stdlib user-facing surfaces require explicit deprecation before removal,
|
|
- unless the change is confined to a new major line.
|
|
|
|
Rationale:
|
|
|
|
- This matches additive-first evolution goals.
|
|
|
|
### 2. Migration Tooling Is Required Only For High-Frequency Or High-Impact Breaks
|
|
|
|
Candidate direction:
|
|
|
|
- some incompatible changes require tooling,
|
|
- others may be served by precise migration notes,
|
|
- and the policy should name the factors that trigger tooling duty.
|
|
|
|
Rationale:
|
|
|
|
- This is more realistic than requiring tools for every break.
|
|
|
|
### 3. Removal Must Be Paired With An Announced Support Boundary
|
|
|
|
Candidate direction:
|
|
|
|
- removal is allowed only with a clearly documented support boundary and migration path or explanation.
|
|
|
|
Rationale:
|
|
|
|
- This makes policy operational rather than rhetorical.
|
|
|
|
## Questions To Resolve In The Room
|
|
|
|
1. Which domains require deprecation before removal?
|
|
2. What triggers mandatory migration tooling?
|
|
3. Can artifact-line changes skip deprecation if they stay behind a new major line?
|
|
4. How should deprecated stdlib APIs be tested in conformance while still supported?
|
|
5. When is documentation-only migration guidance enough?
|
|
|
|
## Expected Outputs
|
|
|
|
1. a decision record for deprecation policy,
|
|
2. a decision record for migration duties,
|
|
3. and lifecycle section targets for `17`.
|
|
|
|
## Explicit Deferrals For Workshop 3
|
|
|
|
- compatibility matrices,
|
|
- published-claim aging,
|
|
- and artifact compatibility line policy.
|
|
|
|
## Inputs
|
|
|
|
- `docs/pbs/specs/2. Governance and Versioning.md`
|
|
- `docs/pbs/specs/13. Conformance Test Specification.md`
|
|
- `docs/pbs/specs/17. Compatibility and Evolution Policy.md`
|
|
- `docs/pbs/agendas/17.1. Compatibility Workshop 1 - Compatibility Domains and Promise Levels.md`
|
|
|