Release guide

Upgrade to opentine 0.4

Historical guide: the current package is v0.5.0. Use the v0.5 upgrade guide for the current package; this page preserves the fork-identity rollout introduced in v0.4.

Version 0.4.0 changes the identity of new portable forks so two interventions at the same step no longer collide. It does not introduce a new storage format: portable *.tine files remain v2 and .tine/ repository objects remain v3.

1. Upgrade without migrating stored data

Terminal

python -m pip install --upgrade "opentine==0.4.0"
python -c "import opentine; print(opentine.__version__)"

# Existing v0.3 artifacts retain their IDs
tine verify representative-v0.3.tine
tine show representative-v0.3.tine

Every artifact written by v0.3.0 still loads under v0.4.0 and keeps its recorded run ID. There is no v0.3-to-v0.4 migration command and opening an old file does not rewrite it.

2. Consume the returned fork ID

fork.py

1from pathlib import Path
2from opentine import Run
3
4source = Run.load("source.tine")
5forked = source.fork(
6    source.steps[2].id,
7    branch="experiment",
8    intent={"reason": "try a safer policy"},
9)
10
11# Use the returned ID; do not predict a default filename.
12destination = Path(f"{forked.id}.tine")
13forked.save(destination)

A default v0.4 fork records source lineage, the retained slice, branch, declared intent, and a random 128-bit nonce in metadata.fork. The run ID is derived from that basis. Callers that hard-coded or recomputed old fork names must switch to the returned Run.id; MCP callers should usenew_run_id.

Terminal

# An explicit destination is easiest to automate.
tine fork source.tine --from-step 2 --save experiment-a.tine
tine fork source.tine --from-step 2 --save experiment-b.tine

# Both forks retain the same prefix, but receive distinct run IDs.
tine diff experiment-a.tine experiment-b.tine

3. Know the reproducibility escape hatches

Ordinary Run.fork() calls draw a nonce and represent distinct interventions.
Cached replay uses an empty nonce internally so the same recorded replay stays deterministic.
Run.fork(..., nonce="") explicitly opts a library caller into reproducible identity.
Run.fork(new_run_id=...) remains available when compatibility code must preserve an explicit legacy ID.

Signatures and verification

New v0.4 signatures cover metadata.fork. The descriptivemetadata.fork_reason field remains unsigned so valid v0.3 signatures stay valid. Fork-ID consistency, artifact integrity, and cryptographic signature verification are related checks, not substitutes for one another.

Repository compatibility

Repository v3 identity is unchanged and identical repository forks can still deduplicate. When writable, Repo.open attempts to recreate expected empty directories that Git or an archive may omit; read-only copies remain readable, and fsck treats a missing packs directory as an empty pack store.

Upgrade checklist

Upgrade all readers and producers to v0.4.0.
Load and verify representative v0.3 artifacts; do not batch re-save them.
Stop predicting portable fork IDs or deriving output filenames from parent IDs.
Use explicit --save destinations in scripts that need stable paths.
Test any code that treats two identical fork points as the same run.

Continue with the current v0.5 guide, forking, replay and resume, or the historical v0.3 repository guide.