# TOON Specification Versioning Policy

This document outlines the versioning policy for the TOON specification.

## Semantic Versioning

The TOON specification follows [Semantic Versioning](https://semver.org/) with a `MAJOR.MINOR` format.

### 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 v3.1 to v3.2 is non-breaking – your implementation keeps working. Moving from v2.1 to v3.0 was a MAJOR transition that required encoder updates.

### Specification Version vs Published Package Version

The specification version (e.g., `3.2`) is `MAJOR.MINOR`. Published npm artifacts (`@toon-format/spec`) use full SemVer `MAJOR.MINOR.PATCH` (e.g., `3.2.0`, `3.2.1`); PATCH releases are packaging or editorial-only and do not change the specification version. Implementations targeting a spec version should pin to the `MAJOR.MINOR` line.

## 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, except strict-mode-only tightening (see Non-Breaking Changes).
- 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.
- Adding a normative decoder requirement that broadens accepted input, compatible with existing encoder output.
- Tightening strict-mode validation (adding new strict-mode errors that formalize previously-undefined behavior). Strict mode is the default, but non-strict mode (`strict=false`) remains a conformant option; documents previously accepted by a non-strict decoder remain accepted.

### 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

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

Implementations should document the supported spec version (e.g. `"toon-spec": "3.2"`) and may support multiple versions concurrently: default to the latest, let users target a specific version, and document version-specific behavior. A new MINOR version keeps existing conformant implementations conformant. A new MAJOR version may require updates; previous-version implementations remain valid, and a migration note is provided in CHANGELOG.md.

## Version History

See [CHANGELOG.md](./CHANGELOG.md) for detailed version history.