Skip to main content

Migration

Use this checklist to migrate projects from TRF v1.x packages to the v2.0 format.

1. Update tooling​

  • Upgrade the CLI: brew upgrade trf-cli or rerun the installer script.
  • Install the latest schemas and profiles from the TRF repository (schemas/v2).
  • Update CI pipelines to use the new CLI Docker image or npm package.

2. Convert manifests​

tw migrate manifest old/manifest.json --output new/manifest.json

Changes in v2:

  • twpack_version replaces format_version.
  • extensions now lists domain identifiers (automotive, ai_ml) instead of package paths.
  • statistics includes link counts and optional coverage metrics.

3. Normalize artifacts​

tw migrate artifacts old/artifacts.jsonl --output new/artifacts.jsonl --profile minimal
  • v2 requires kind (v1 used type).
  • IDs must follow the namespace convention (req:, test:). Add prefixes where missing.
  • Move custom fields into the fields object; top-level custom keys are deprecated.
tw migrate links old/links.jsonl --output new/links.jsonl
  • relation replaces type.
  • Add confidence (default 1.0) and rationale for future traceability reviews.
  • Ensure from/to reference updated IDs after artifact migration.

5. Rebuild packages​

tw build out/new.twpack \
  --source new/artifacts.jsonl requirement \
  --source new/links.jsonl link \
  --profile automotive_safety
  • Attachments from v1 can be reused; ensure hashes are recalculated automatically during build.
  • Sign the package if you previously relied on external signing workflows.

6. Validate​

tw validate out/new.twpack --full
trf-validator out/new.twpack --strict

Resolve any schema or coverage failures before promoting the new package.

7. Archive old packages​

  • Retain the original v1 packs for audit history.
  • Tag repository releases noting the last v1 package and the first v2 package.
  • Communicate the migration timeline to suppliers and customers; provide them with updated profiles and schemas.

Need help automating the transformation? Check the migration scripts in the TRF repository (tools/migration-scripts/) or open a discussion in the project community.