release

Release Checklist

1. Update local state:

   1. git checkout main && git pull
   2. git status --porcelain=v1 (must be clean)

2. Prepare a code PR (feature/fix changes):

   1. Create branch from main
   2. Make changes
   3. If you touched packages/node (or anything that affects the legacy transloadit clone):
      1. Run corepack yarn check (this may reformat files and/or auto-fix Knip findings)
      2. Run corepack yarn verify:full locally once before pushing.
         • This catches wrapper sync drift early and still runs the deeper repo checks.
      3. If verify / verify:full fails with transloadit wrapper drift, run node scripts/prepare-transloadit.ts, commit the tracked packages/transloadit updates, and re-run corepack yarn verify:full.
   4. If you add a changeset for @transloadit/node, also add a similar changeset for @transloadit/mcp-server if it could affect its workings. The chances are, they are, since the latter is mostly a thin wrapper around the former.
      • This repo enforces a one-way coupling: node releases should also publish a new mcp-server version (but mcp-server releases do not require node releases).
      • yarn check/yarn verify will fail fast if you forget.
   5. Commit + push branch
   6. Open PR, wait for CI green
   7. Squash-merge the PR

   Notes:

   1. When creating PRs with gh pr create from a shell, avoid unescaped backticks in the --body string. Prefer --body-file to prevent accidental command substitution.
   2. If you use gh run watch heavily, GitHub may throttle with HTTP 429. Prefer gh pr checks <PR_NUMBER> with occasional polling (or use the web UI) if you hit throttling.

   Optional parity playbook (release/debug only):

   1. Update the parity baseline:
      1. node scripts/prepare-transloadit.ts
      2. node scripts/fingerprint-pack.ts ./packages/transloadit --ignore-scripts --quiet --out ./docs/fingerprint/transloadit-baseline.json
      3. cp ./packages/transloadit/package.json ./docs/fingerprint/transloadit-baseline.package.json
   2. Immediately reformat the baseline:
      1. corepack yarn fix:js
   3. Run corepack yarn parity:transloadit
   4. Commit + push if you intentionally want to update the recorded baseline

3. Merge the "Version Packages" PR (changesets action):

   1. Wait for the Version Packages PR to appear (or update)
   2. Checkout that branch locally:
      1. git fetch origin changeset-release/main
      2. git checkout changeset-release/main
   3. Ensure yarn.lock is up to date (CI will fail otherwise):
      1. corepack yarn
      2. If yarn.lock changed: git add yarn.lock && git commit -m "chore: update yarn.lock for release" && git push
   4. Verify the Version Packages PR includes all expected linked/versioned packages:
      1. Read the # Releases section (this is the authoritative "what will publish")
      2. If you expect a linked package to bump (e.g. @transloadit/node and transloadit), ensure the PR updates both. If it doesn't, fix before merging (otherwise tags/releases can drift).
   5. Ensure CI is green for the PR
   6. Squash-merge the PR

   Notes:

   1. The Version Packages PR may show no required checks in the PR UI in some setups; verify by checking recent runs:
      1. gh run list --branch changeset-release/main --limit 3

4. Immediately after merging the Version Packages PR:

   1. git checkout main && git pull
   2. Update the lockfile (required for the Release workflow):
      1. corepack yarn
      2. If yarn.lock changed: git add yarn.lock && git commit -m "chore: update yarn.lock for release" && git push
      3. Reason: the Release workflow runs corepack yarn with immutable installs and will fail if it would modify yarn.lock.
   3. Run corepack yarn check (catches formatting/knip/ts/unit drift early)

5. Prevent the packages/transloadit clone from drifting (special case):

   1. If the transloadit package exists in this repo, keep it in sync with @transloadit/node by running:
      1. git checkout main && git pull
      2. node scripts/prepare-transloadit.ts
      3. Refresh parity baselines (if they changed):
         1. node scripts/fingerprint-pack.ts ./packages/transloadit --ignore-scripts --quiet --out ./docs/fingerprint/transloadit-baseline.json
         2. cp ./packages/transloadit/package.json ./docs/fingerprint/transloadit-baseline.package.json
      4. corepack yarn check
      5. If anything changed, commit + push to main