Skip to content

VERSIONING.md

Latest commit

 

History

History
137 lines (87 loc) · 4.13 KB

VERSIONING.md

File metadata and controls

137 lines (87 loc) · 4.13 KB

TOON Specification Versioning Policy

This document outlines the versioning policy for the TOON specification.

Semantic Versioning

The TOON specification follows Semantic Versioning with a MAJOR.MINOR format (specifications don't need PATCH versions).

Version Format

MAJOR.MINOR

  • MAJOR version - Incremented for breaking changes that are incompatible with previous versions
  • MINOR version - Incremented for backward-compatible additions, clarifications, or non-breaking changes

Example: Moving from v1.5 to v1.6 means your implementation keeps working. Moving from v1.5 to v2.0 means you'll likely need to update your code.

What Constitutes a Breaking Change

Breaking changes (requiring a MAJOR version bump) include:

Syntax Changes

  • Removing or changing existing syntax.
  • Changing the meaning of existing constructs.
  • Adding new reserved characters that could conflict with existing valid TOON documents.
  • Changing encoding/decoding behavior in incompatible ways.

Semantic Changes

  • Changing how valid TOON should be interpreted.
  • Modifying type conversion rules in incompatible ways.
  • Changing quoting rules in ways that break existing documents.
  • Altering delimiter behavior.

Conformance Changes

  • Making previously valid TOON invalid.
  • Adding new MUST requirements that existing implementations don't meet.
  • Changing error handling in ways that break round-trip compatibility.

What Constitutes a Non-Breaking Change

Non-breaking changes (MINOR version bump) include:

Clarifications

  • Clarifying ambiguous language without changing behavior.
  • Adding examples to illustrate existing rules.
  • Improving specification wording for clarity.
  • Adding informative (non-normative) sections.

Backward-Compatible Additions

  • Adding optional features that don't affect existing documents.
  • Adding new SHOULD or MAY recommendations.
  • Expanding the specification to cover previously undefined behavior (if done in a backward-compatible way).
  • Adding new test cases that existing conformant implementations already pass.

Documentation Improvements

  • Grammar and typo fixes.
  • Reorganizing content for better readability.
  • Adding cross-references.
  • Improving examples.

Version Lifecycle

Working Draft

  • Current development version.
  • May receive updates without version changes.
  • Indicated by "Status: Working Draft" in the specification.

Stable Release

  • Released versions are immutable.
  • Version number is assigned when changes are merged.
  • Previous versions remain available for reference.

Deprecation

If we need to make a breaking change (MAJOR version bump):

  1. Announcement: We add a deprecation notice to the current spec
  2. Migration Period: The next MINOR version includes migration guidance
  3. New Major Version: Breaking changes are released in the next MAJOR version
  4. Support: Previous MAJOR versions remain available – we don't break old links

Implementation Compatibility

Specification Version Support

If you're implementing TOON, clearly document which spec version you support:

{
  "toon-spec": "1.3"
}

This helps users know what behavior to expect.

Forward Compatibility

Your implementation can support multiple spec versions. If you do:

  1. Default to the latest supported version
  2. Let users specify which version to target
  3. Document version-specific behavior clearly

Backward Compatibility

When a new MINOR version is released:

  • Your implementation stays conformant – no code changes needed
  • Updates may be recommended but aren't required

When a new MAJOR version is released:

  • You may need updates to support the new version
  • Previous version implementations remain valid
  • We'll provide a migration guide

Version History

See CHANGELOG.md for detailed version history.

Questions

Not sure if your proposed change is breaking or non-breaking?

  1. Open an issue with the [RFC] tag
  2. Describe the proposed change
  3. Ask for feedback from maintainers and community

When in doubt, we err on the side of caution and treat potentially breaking changes as MAJOR version bumps.