# 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`