discussion framework migration
This commit is contained in:
@@ -0,0 +1,153 @@
|
||||
# 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.
|
||||
- For executable FE/BE conformance-relevant code changes, the backend conformance matrix (`docs/general/specs/22. Backend Spec-to-Test Conformance Matrix.md`) MUST be updated and pass hard-gate policy checks.
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user