prometeu-studio/docs/pbs/agendas/17. Compatibility and Evolution Policy Agenda.md

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