---
name: release
description: Checklist for releasing packages from this monorepo (code PR -> Version Packages PR -> npm publish).
---

# 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`

6. Monitor the `Release` workflow on `main`:
   1. `gh run list --workflow Release --branch main --limit 5`
   2. `gh run watch <run_id>`
   3. If it fails after publishing due to a missing tag:
      1. Identify the missing tag in the job logs (it will look like `<pkg>@<version>`)
      2. Create/push the missing tag from `main`:
         1. `git checkout main && git pull`
         2. `git tag <pkg>@<version>`
         3. `git push origin <pkg>@<version>`
      3. If needed, create a GitHub release:
         1. `gh release create <pkg>@<version> --generate-notes`

7. Verify what should have been published:
   1. In the merged `Version Packages` PR, read the `# Releases` section to get the authoritative list.

8. Verify npm publish for each released package:
   1. For each `<pkg>@<version>` in the `# Releases` section:
      1. `npm view <pkg> version` (should match)
      2. `git tag -l '<pkg>@<version>'` (tag should exist)
   2. If npm versions look stale, wait ~60s and retry (registry propagation)