Release guide

Upgrade to opentine 0.3

Historical guide: the current package is v0.5.0. Use the v0.5 upgrade guide for the current package. The v0.4 guide remains the reference for fork-act identity.

Version 0.3.0 is the first public release containing the provider-neutral billing work developed under 0.2.1. There is no v0.2.1 tag or PyPI distribution to install.

1. Upgrade without changing formats

Terminal

# Upgrade every reader and producer
python -m pip install --upgrade "opentine==0.3.0"
python -c "import opentine; print(opentine.__version__)"

# Existing portable files remain v2
tine verify representative.tine
tine show representative.tine
tine cost representative.tine

Portable .tine files stay format v2. Existing Run, Agent, signing, replay, and total_cost APIs remain available. Python 3.11 through 3.14 is supported.

2. Opt into repository v3

Terminal

# Create a separate v3 repository
tine init .

# Fail-closed import into a named ref
tine migrate-v3 representative.tine --repo . --ref heads/imported
tine fsck --repo .
tine repo-log heads/imported --repo .

migrate-v3 is an import, not an in-place rewrite. It stores the exact v2 bytes as a legacy blob, records the source integrity and signature result, creates redacted v3 objects with new identities, and retains a deterministic step-to-event ID map.

Verification and secrets

Import fails closed when source integrity fails or a requested signature cannot be verified. --allow-unverified is an explicit quarantine escape hatch and the failed result remains recorded. Because the byte-exact legacy blob is deliberately unredacted, review it for credentials before packing, pushing, or cloning the repository.

Compatibility boundary

Use tine migrate only for portable v1-to-v2 migration.
Use tine migrate-v3 only to import a portable v2 file into a .tine/ repository.
A legacy signature applies to the retained legacy blob, not the generated v3 objects.
Keep original artifacts until repository verification and downstream reads succeed.

Continue with the current v0.5 guide, repository v3, recording and imports, or the historical v1-to-v2 guide.