prometeu-studio/docs/pbs/specs/2. Governance and Versioning.md

PBS Governance and Versioning

Status: Draft v1
Applies to: PBS language, profiles, and related specifications

1. Purpose

This document defines how PBS decisions are made and how versions evolve without breaking the ecosystem unpredictably.

2. Scope

This policy governs:

• language specification changes,
• profile changes (for example, Core/Game),
• standard library specification changes,
• compatibility policy updates,
• release and deprecation decisions.

3. Governance Model

PBS uses a spec-first governance model. No implementation change is considered normative until the relevant spec change is accepted.

3.1 Roles

• Maintainers: approve/reject RFCs and cut releases.
• Editors: keep specs coherent, complete, and cross-referenced.
• Implementers: provide feasibility feedback and conformance evidence.
• Community contributors: propose RFCs and review drafts.

3.2 Authority Rule

If a governance decision conflicts with runtime/bytecode authority, runtime/bytecode authority wins.

4. Decision Process (RFC)

All non-trivial changes MUST go through RFC.

4.1 RFC Lifecycle

1. Draft: problem, proposal, alternatives, migration impact.
2. Review: open feedback period.
3. Decision: Accepted, Rejected, or Deferred.
4. Spec Merge: normative documents updated.
5. Implementation: only after spec merge.
6. Conformance: tests and diagnostics updated before release.

4.2 Fast-Track

Fast-track is allowed only for:

• critical correctness fixes,
• security/capability violations,
• deterministic behavior regressions.

Fast-track changes still require post-merge RFC backfill.

5. Version Domains

PBS versioning is separated by domain to avoid ambiguity.

1. Language Version (pbs_lang): syntax + semantics.
2. Profile Version (pbs_profile): profile-specific surface (Core/Game).
3. Stdlib Version (pbs_stdlib): standard library contract.
4. Compatibility Policy Version (pbs_compat): evolution/deprecation policy text.

Host primitives remain versioned by canonical identity (module, name, version). Direct declaration of canonical host primitive bindings is reserved to SDK/toolchain-managed declare host surfaces, not ordinary user-authored PBS modules. User-facing PBS and stdlib APIs over host primitives MAY evolve independently from those bindings as long as canonical host identity, capability policy, and compatibility commitments remain preserved.

6. Versioning Scheme

Each domain uses semantic versioning:

• MAJOR: incompatible changes.
• MINOR: backward-compatible additions.
• PATCH: clarifications/fixes with no intended behavior break.

7. Change Classification

7.1 Patch Changes

• wording fixes,
• unambiguous typo corrections,
• diagnostics wording adjustments without code/behavior contract changes.

7.2 Minor Changes

• additive syntax behind explicit profile gates,
• new stdlib APIs,
• new host primitive versions added without removing old supported versions.

7.3 Major Changes

• behavior changes that can alter valid program outcomes,
• removal of previously supported constructs,
• incompatible type or resolution rule changes.

8. Compatibility Rules

• Supported old versions MUST continue to compile/link/run as declared by the compatibility window.
• A release MUST publish a compatibility matrix for language/profile/stdlib domains.
• Toolchains MUST reject unsupported targets deterministically with explicit diagnostics.

9. Deprecation and Removal Policy

Deprecation stages:

1. Introduce deprecation notice in specs and tooling.
2. Keep feature functional during declared support window.
3. Remove only in a subsequent major version.

Every deprecation MUST include:

• replacement path,
• migration notes,
• timeline (first deprecated version, last supported version, removal version).

10. Release Requirements

Before any version release:

1. Specs for changed domains are updated.
2. Changelog is published with change classification.
3. Conformance suite is updated and passing.
4. Compatibility matrix is published.
5. Migration guide is provided for any major-impact changes.

11. Documentation Contract

Every accepted change MUST update, when relevant:

• normative spec sections,
• examples,
• diagnostics documentation,
• conformance tests,
• compatibility matrix/changelog.

12. Conflict Resolution

When maintainers disagree, the tie-breaker is:

1. determinism and compatibility,
2. clarity for beginners,
3. implementation feasibility and tooling stability.

13. Non-Goals

• Replacing runtime authority with governance-only decisions.
• Defining subsystem-specific API semantics in this document.
• Granting implementation behavior override over normative specs.