prometeu-studio/docs/pbs/agendas/17.2. Compatibility Workshop 2 - Deprecation, Removal, and Migration Duties.md

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