151 lines
4.3 KiB
Markdown
151 lines
4.3 KiB
Markdown
# 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)`.
|
|
|
|
## 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.
|