Docs Versioning Policy

Versioning Policy

Plumego follows a strict, conservative versioning policy.

Version numbers are not signals of progress or excitement.
They are signals of risk.

This document defines:

  • How Plumego versions are structured
  • What each version change means
  • What guarantees users can rely on
  • How breaking changes are handled

If you depend on Plumego in production,
this page matters more than any feature list.

Semantic Versioning (SemVer)

Plumego follows Semantic Versioning:

MAJOR.MINOR.PATCH

Each segment has a non-negotiable meaning.

PATCH Releases (x.y.Z)

Patch releases are the safest kind of change.

They may include:

  • Bug fixes
  • Documentation fixes
  • Internal refactors that do not change behavior
  • Performance fixes that preserve semantics

They must not include:

  • API changes
  • Behavior changes
  • New public APIs
  • Removal of any documented behavior

If a change alters observable behavior,
it does not belong in a patch release.

MINOR Releases (x.Y.z)

Minor releases are additive and backward compatible.

They may include:

  • New public APIs
  • New optional helpers
  • Expanded documentation
  • New reference pages
  • Additional examples

They must not include:

  • Breaking changes
  • Removal of public APIs
  • Semantic changes to existing behavior

Code compiled against an older minor version
must continue to work without modification.

MAJOR Releases (X.y.z)

Major releases are rare and deliberate.

They may include:

  • Breaking API changes
  • Removal of deprecated APIs
  • Behavioral changes
  • Core architectural shifts (rare)

Major releases require:

  • Clear motivation
  • Explicit migration guides
  • Advance documentation
  • Justification against design principles

A major version bump is treated as a last resort.

What Counts as a Breaking Change

The following are considered breaking changes:

  • Changing a public API signature
  • Changing middleware execution semantics
  • Changing routing behavior
  • Changing Context guarantees
  • Removing or renaming public APIs
  • Changing documented defaults
  • Changing error semantics

If users must modify their code,
the change is breaking.

What Does Not Count as Breaking

The following are not breaking changes:

  • Bug fixes restoring documented behavior
  • Performance improvements with identical semantics
  • Internal refactors
  • Adding new APIs
  • Improving error messages
  • Expanding documentation

Observable correctness beats compatibility with bugs.

Deprecation Policy

Plumego prefers deprecation over removal.

Deprecation rules:

  • Deprecated APIs remain functional
  • Deprecation is documented explicitly
  • Removal only happens in a future major release
  • Deprecation periods are measured in releases, not days

Silent deprecation is forbidden.

Compatibility Guarantees

Within a major version, Plumego guarantees:

  • Source compatibility
  • Behavioral stability
  • Documented semantics remain valid

If behavior diverges from documentation,
it is treated as a bug.

Documentation and Versioning

Documentation is versioned alongside code.

Rules:

  • Reference reflects current version behavior
  • Deprecated APIs are marked clearly
  • Migration guides are written before release
  • Changelogs reflect real impact, not marketing language

Undocumented changes are considered defects.

Versioning and Ecosystem Packages

Optional companion packages follow the same principles,
but may evolve independently.

Constraints:

  • Core versioning is authoritative
  • Companion packages must document compatibility ranges
  • Core stability is never compromised for ecosystem convenience

Pre-1.0 Versions (If Applicable)

If Plumego ever enters a 0.x.y phase:

  • APIs may change more frequently
  • Stability guarantees are reduced
  • Documentation still reflects intent

However, once 1.0.0 is released,
all rules in this document apply fully.

Why Plumego Is Conservative About Versions

Frequent breaking changes:

  • Increase cognitive load
  • Break trust
  • Force unnecessary rewrites
  • Reward short-term experimentation over long-term use

Plumego optimizes for:

  • Longevity
  • Predictability
  • Institutional memory

Version numbers are part of that contract.

Summary

Plumego versioning is built on restraint.

  • Patch means safe
  • Minor means additive
  • Major means deliberate breakage

Nothing else is acceptable.

If Plumego ever violates this policy,
it has failed its users.

  • Roadmap Overview — long-term direction
  • Design Principles — constraints on change
  • Non-Goals — what will never be added
  • Planned Features — possible evolution paths

Versioning is not about progress —
it is about keeping promises over time.