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?

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