Skip to content
AAOE
Draft2 min read

Versioning and Evolution

Purpose

This specification defines how AAOE Specifications evolve while preserving historical traceability, engineering continuity, and governance consistency.

Versioning enables the Body of Knowledge to mature without losing the engineering rationale behind previous guidance.

Evolution Principles

Specification evolution shall be:

  • traceable
  • transparent
  • incremental whenever practical
  • historically preserved
  • evidence-driven
  • backwards understandable

Every published version becomes part of the historical record.

Version Categories

AAOE Specifications use semantic versioning.

Major.Minor.Patch

Example:

1.0.0

Meaning:

  • Major — incompatible governance or normative changes.
  • Minor — new guidance while preserving existing intent.
  • Patch — clarifications, corrections, editorial improvements.

Version numbers describe document evolution rather than software releases.

Compatible Evolution

Changes considered compatible include:

  • clarification
  • improved wording
  • additional examples
  • expanded rationale
  • non-breaking refinements

These normally result in Minor or Patch revisions.

Incompatible Evolution

Changes considered incompatible include:

  • removal of normative guidance
  • conflicting governance principles
  • fundamental conceptual changes
  • altered terminology affecting interpretation

These require a new Major version.

Supersession

A Specification may be superseded when:

  • engineering knowledge substantially evolves
  • a broader Specification replaces it
  • governance determines replacement is preferable

Superseded Specifications remain permanently available. Historical references shall not be removed.

Historical Preservation

Historical versions shall:

  • remain accessible
  • preserve identifiers
  • preserve publication history
  • preserve traceability

Historical artifacts contribute to the evolution of engineering knowledge.

Relationship to Traceability

Traceability shall exist across versions. Where applicable, each revision should identify:

  • previous version
  • successor version
  • rationale for change
  • supporting Discoveries
  • supporting ADRs

Relationship to Specification Governance

GV-0007 defines how Specifications are governed. GV-0008 defines how governed Specifications evolve over time. These specifications are complementary.

Deprecation

Specifications may be designated as deprecated before supersession. Deprecation indicates that newer guidance is preferred while preserving compatibility with existing references.

Deprecation does not remove historical validity.

Future Evolution

Future Governance Specifications define:

  • Knowledge Domains