Versioning Policy
How documentation evolves without rewriting history: forward-only updates, changelog rules, snapshot interpretation, and SSOT boundaries.
Overview
This page defines how PVERSE documentation changes over time. The documentation is treated as an operational record of system meaning, not as editable marketing copy. Changes must preserve history, remain auditable, and avoid silent reinterpretation.
The goal is not to freeze docs forever. The goal is to let the documentation evolve without erasing what earlier readers were told. That means forward-only clarification, durable changelog practice, clear version interpretation, and a stable boundary between semantic meaning and SSOT-owned numeric parameters.
Scope
This page defines the documentation evolution model used across PVERSE Docs.
- forward-only documentation updates and when a meaning change must be recorded
- the docs version model and when major, minor, or patch bumps are required
- the distinction between changelog history and snapshot-style current-state pages
- the relationship between docs meaning, SSOT numeric sources, and code enforcement
Core Model
PVERSE documentation follows a forward-only model. Meaning may evolve, but prior meaning must remain readable. Clarification should usually be additive, and interpretation changes must be traceable through changelog entries rather than hidden inside silent rewrites.
- never rewrite meaning silently
- append clarification when a sentence becomes incomplete or ambiguous
- link meaning changes through the changelog so readers can reconstruct history
- treat docs versions as documentation-meaning markers, not software release tags
Operational Behavior
In ordinary maintenance, spelling fixes, formatting changes, accessibility updates, or non-semantic examples may be edited without treating the page as a new meaning version. But once a page changes how the system should be interpreted, that is no longer just cleanup. It becomes versioned documentation work and must be recorded accordingly.
In larger changes, such as reorganizing lanes, renaming canonical routes, clarifying a protocol boundary, or updating policy interpretation, the docs set should receive a version bump and the affected pages should be linked from the changelog. Snapshot pages may summarize the present state, but they must not replace the historical record of how meaning evolved.
Constraints
- docs versioning does not represent software release tags, deployment timestamps, or token contract versions
- SSOT numeric changes do not automatically require a docs version bump unless the interpretation itself changes
- snapshot pages summarize current state but do not replace changelog history
- publicly referenced pages should not be removed without redirects and a deprecation trail
Integrity Considerations
Documentation integrity depends on preserving both semantic history and present readability. If a page quietly changes meaning, readers lose the ability to tell what was promised, clarified, or re-scoped. This page exists to keep that from happening by separating formatting work from meaning work and by making history readable instead of disposable.
- history remains reconstructable through versioning and changelog records
- meaning changes are explicit and attributable rather than implied by silent edits
- older pages stay readable even when newer interpretations exist
Forward-only documentation
Documentation follows a forward-only policy. Meaning may evolve, but prior meaning remains readable. When interpretation changes, the change is recorded and linked through the changelog rather than silently replacing the old record.
- Never rewrite meaning silently.
- Append clarification. Add a note, updated section, or explicit interpretation update.
- Link the record. Changelog entries should point to impacted pages.
Documentation version model
Docs versions describe structural or semantic evolution of the documentation set. They do not represent software releases, deployment timing, or token contract versions.
- Major — structural re-architecture of docs such as lane splits, merges, or canonical hierarchy changes
- Minor — meaningful expansion such as new lanes, new reference surfaces, or new policy pages
- Patch — corrections that do not change meaning, such as typos, formatting, or accessibility improvements
What requires a version bump
A docs version increments when one of the following occurs:
1) Structural change
- adding, removing, splitting, or merging a lane
- changing canonical page hierarchy or navigation grouping
- renaming canonical routes in a way that changes docs-map meaning
2) Meaning change
- clarifying protocol boundaries or guarantees
- updating policy interpretation
- changing definitions that affect how the system is understood
What does not require a version bump
- spelling and grammar corrections
- style, layout, or typography changes
- adding examples that do not change meaning
- accessibility improvements such as ARIA labels, skip links, or contrast fixes
Changelog policy
All meaning changes must be recorded in the docs changelog. The changelog is the documentation history ledger and the canonical place to answer what changed, when it changed, and how interpretation moved forward.
A changelog entry should include:
- Date with a clearly labeled timezone
- Scope such as Docs, Whitepaper, Infrastructure, or Token
- Type such as Meaning change, Structure change, Clarification, or Deprecation
- Links to impacted pages
- Summary explaining the changed interpretation
Snapshot policy
Snapshot pages represent the current state at the time they are read. They help operators and readers understand what is true right now, but they do not replace history. The changelog remains the canonical record of how meaning evolved over time.
- Changelog = historical record of what changed, when, and why
- Snapshot = current-state summary of what is true right now
SSOT relationship
PVERSE separates responsibilities as follows:
- SSOT defines numeric parameters and canonical configuration
- Docs define meaning and boundaries
- Code enforces transitions and produces records
Numeric SSOT changes do not require a docs version bump unless the interpretation changes. If meaning changes, that change must be documented and logged even when the trigger came from a numeric source update.
Backward readability & compatibility
Documentation should remain readable across time. Older pages should not become misleading simply because a newer policy exists. When necessary, add clearly labeled interpretation updates and link the relevant changelog entry.
- prefer additive clarification over replacement
- when deprecating a concept, mark it as deprecated and point to the replacement
- do not remove publicly referenced pages without redirects and deprecation notes
Examples
Example: SSOT tuning (no version bump)
Mining distribution or fee values change in SSOT, but the docs meaning remains correct. Result: no version bump. A snapshot update may still be useful for operators.
Example: Meaning change (version bump + changelog)
A policy is clarified, such as market activation sequence or finality interpretation. Result: version bump and a changelog entry linking the updated pages.
Example: Structure change (version bump)
A new lane is introduced or navigation hierarchy is reorganized. Result: version bump and a changelog entry describing the structural change.
Future Expansion
This page may expand over time as PVERSE adds richer version markers, deprecation conventions, archive policies, and more explicit docs-lane governance. Even as the docs tree grows, this page should remain the canonical rulebook for how documentation changes without losing historical meaning.
Summary
- documentation evolves forward and does not silently rewrite history
- version bumps are required for structural or semantic change, not for pure formatting work
- changelog records meaning history, while snapshot pages summarize present state
- docs define meaning, SSOT defines numbers, and code enforces transitions