Release guide

Migrate to opentine 0.2

Historical guide: the current package is v0.5.0. Use the v0.5 upgrade guide for the current package and interoperability surface.

The compatibility rule is asymmetric: 0.2 reads v1 and v2, while 0.1.x cannot read v2. Loading v1 is non-destructive; saving is the upgrade boundary.

# 1. Upgrade the reader
pip install --upgrade "opentine==0.2.0"

# 2. Verify and preview
tine verify representative-v1.tine
tine migrate representative-v1.tine --dry-run

# 3. Keep both versions during rollout
tine migrate representative-v1.tine --save representative-v2.tine
tine verify representative-v2.tine

Team rollout

1. Upgrade every reader and automation path that must consume new artifacts.
2. Verify representative v1 files and dry-run their migrations.
3. Write v2 copies and exercise show, fork, replay, and diff.
4. Update producers so newly created artifacts are v2.
5. Retire v1-only consumers before migrating archives in place.

Legacy linear files

The best-effort 0.1.0 linear importer recomputes step IDs. Preserve the original, inspect the result, and treat it as an import rather than byte-identical preservation.

What v2 enables

Format v2 adds stable homes for tags, usage and budgets, draft autosaves, tine-sig/1 signatures, and migration metadata. The v0.2 diff implementation also adds field-level comparison.

Continue with the current v0.5 guide, or read the v0.3 repository guide to understand the separate v3 object store.