Framework Versioning

TRF follows semantic versioning (MAJOR.MINOR.PATCH) and provides tooling to manage schema evolution, profiles, and extensions.

Version classes

• Major releases – Structural changes to artifacts/links, new mandatory fields, or breaking CLI options. Occur roughly once per year.
• Minor releases – Backward-compatible additions (new artifact kinds, validation rules, commands). Quarterly cadence.
• Patch releases – Bug fixes and documentation updates. As needed.

Compatibility guarantees

Component	Major change	Minor change
Artifact schemas	May introduce required fields	Adds optional fields or enums
Link schemas	May rename relations	Adds new relation definitions
TWPack layout	Stable	Stable
CLI commands	May deprecate/remove	Adds flags, keeps existing flags
Validator	May require schema updates	Backward-compatible

TWPack archives declare their target schema version in manifest.json (schema_version). Validators ensure the correct schema set is available.

Managing upgrades

1. Read release notes – Highlight new artifact kinds, validation changes, migration scripts.
2. Update tooling – Upgrade CLI/validator; download new schemas and profiles from the TRF repo.
3. Run migration scripts – Use tw migrate helpers to rename fields, adjust IDs, or update manifests.
4. Validate – Run tw validate --full on existing packs to catch issues early.
5. Tag releases – Record the TRF version used for each TWPack submitted externally.

Deprecation process

1. Feature flagged for deprecation in release notes and documentation.
2. CLI emits warnings for one minor release cycle.
3. Deprecated feature disabled in the next major release.
4. Migration guidance accompanies the major release.

Use tw doctor to scan repositories for deprecated fields or commands.

Extension lifecycle

• Extension packages declare compatibility ranges ("requires_trf": ">=2.0 <3.0").
• Update extensions independently of core releases as long as compatibility constraints are satisfied.
• Keep extension schemas in schemas/extensions/<name>/<version>/ so older packs remain reproducible.

Long-term support

• LTS releases are published every two years and receive bug fixes for five years.
• Organizations may stay on an LTS release while monitoring newer features in non-LTS channels.
• Security fixes and critical validation updates are backported when feasible.

Tooling aids

• tw upgrade --check – Reports available CLI updates.
• tw migrate manifest|artifacts|links – Applies schema transformations.
• tw diff --schema – Highlights schema differences between TRF versions.

Stay informed via the TRF changelog and project discussions. When planning major compliance submissions, lock the TRF version in manifest.json and your CI configuration to avoid unexpected changes.