npm ci
npm run devnpm run build
npm run check
npm run test:e2eWhen component APIs change, regenerate and commit the generated files:
npm run build:codegenInclude a changeset with changes that need a release:
npx changesetChoose the version bump, describe the user-visible change, and commit the generated file with your implementation. Docs-only and development-tooling changes do not need a changeset.
Review and merge the release PR when ready. Click Approve workflows to run on the PR if its checks are waiting for approval. To refresh it manually, run the Update release PR workflow on main.
When the release PR merges, CI tags the commit that set the new version as
v<version> and starts the Release workflow
on that tag. To release a different commit, tag it yourself:
gh api repos/convex/aggregate/git/refs -f ref=refs/tags/v1.2.3 -f sha=<commit>Or, from a local clone: git tag v1.2.3 <commit> && git push origin v1.2.3.
The tag must match package.json's version. Stable releases must be on main;
the commit may be older than the current tip. GitHub runs the release workflow
from the tagged commit, so the commit must include it. The workflow builds and
tests that commit, then stages the tested package on npm.
Review the package on npm's Staged Packages page and approve with 2FA, or run:
npm stage approve <stage-id>Use the stage ID from the workflow log. Approve versions in order to avoid
moving latest backward.
To prepare a release locally instead of using the bot:
npm ci
npm run build
npm run check
npx changeset versionReview and commit the version, changelog, and consumed changesets, then merge through a checked PR.
For a branch prerelease, prepare a prerelease version with Changesets on that
branch and tag its commit, such as v1.2.3-alpha.0. The first prerelease
identifier selects the npm channel, such as alpha.
The tag records intent to release; npm is the source of truth for what was staged. If the workflow fails, check npm's staged packages first:
-
Tagged, but Release didn't start: start it on the tag with
gh workflow run release.yml -R convex/aggregate --ref v1.2.3. -
Not staged: rerun the failed jobs (
gh run rerun <run-id> -R convex/aggregate --failed), for example after pushingmainif the tag went first. A rerun uses the run's original commit and works for 30 days.To release a different commit, fix the source and move the tag:
gh api -X PATCH repos/convex/aggregate/git/refs/tags/v1.2.3 -f sha=<commit> -F force=true
-
Staged, but rejected in review:
npm stage reject <stage-id>frees the version, so you can move the tag to a corrected commit. A published version cannot be reused; prepare a new version instead.