transloadit/node-sdk/release

Release Checklist

1. Update local state:
2. git checkout main && git pull
3. git status --porcelain=v1 (must be clean)

1. Prepare a code PR (feature/fix changes):
2. Create branch from main
3. Make changes
4. If you touched packages/node (or anything that affects the legacy transloadit clone):
5. Run corepack yarn check (this may reformat files and/or auto-fix Knip findings)
6. Run corepack yarn verify:full locally once before pushing.

• This catches wrapper sync drift early and still runs the deeper repo checks.

1. 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.
2. Classify changes using the versioning policy.

• API2 contract type/schema changes ship in minors, with a Contract: summary and a

Type-breaking: line per type break. Description-only syncs are patches; pre-1.0 package exceptions follow the policy.

• Every major changeset must contain a nonempty SDK-breaking: line naming the SDK surface

it breaks. yarn lint:changesets enforces this for each file.

1. 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.

1. Commit + push branch
2. Open PR, wait for CI green
3. 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.

1. 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:
2. node scripts/prepare-transloadit.ts
3. node scripts/fingerprint-pack.ts ./packages/transloadit --ignore-scripts --quiet --out ./docs/fingerprint/transloadit-baseline.json
4. cp ./packages/transloadit/package.json ./docs/fingerprint/transloadit-baseline.package.json
5. Immediately reformat the baseline:
6. corepack yarn fix:js
7. Run corepack yarn parity:transloadit
8. Commit + push if you intentionally want to update the recorded baseline

1. Merge the "Version Packages" PR (changesets action):
2. Wait for the Version Packages PR to appear (or update)
3. Checkout that branch locally:
4. git fetch origin changeset-release/main
5. git checkout changeset-release/main
6. Ensure yarn.lock is up to date (CI will fail otherwise):
7. corepack yarn
8. If yarn.lock changed: git add yarn.lock && git commit -m "chore: update yarn.lock for release" && git push
9. Verify the Version Packages PR includes all expected linked/versioned packages:
10. Read the # Releases section (this is the authoritative "what will publish")
11. 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).

1. Ensure CI is green for the PR
2. 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:
2. gh run list --branch changeset-release/main --limit 3

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

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

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

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

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