Release

Release Package

Release a package to NPM. Ensures version bump, changelog, release branch, CI pipeline, and npm publish.

The package is identified by the <package-name> argument, which is the directory name under packages/ (e.g., ocr-ggml, sdk, tts-ggml). The skill reads packages/<package-name>/package.json to determine the package type and npm scope.

Usage

/release <package-name> [base-branch]

Where:

• <package-name> is the directory name under packages/ (e.g., ocr-ggml, tts-onnx)
• [base-branch] is optional — the branch to create the release from. Defaults to main. Use this for patches, e.g., /release ocr-ggml release-ocr-ggml-0.11.0

Workflow

Step 1: Validate prerequisites

1. Read packages/$ARGUMENTS/package.json to get the current version and npm package name.

2. Compare version against the latest version published on npm:

   npm view <npm-package-name> version

3. If the local version is not higher than the npm version, stop and ask the user to bump the version first.

4. Verify the CHANGELOG heading format exactly matches what the publish-release workflow extracts. The workflow uses this awk regex: ^## \[<version>\] — heading must be bracketed (Keep-a-Changelog style). Soft phrasing like "section for 0.1.0" is not enough; the heading line must literally be ## [0.1.0].

   Run this exact check (mirrors the regex in .github/workflows/create-github-release.yml):

   version=$(node -p "require('./packages/<package>/package.json').version")
   if ! grep -qE "^## \[${version}\]" "packages/<package>/CHANGELOG.md"; then
     echo "FAIL: packages/<package>/CHANGELOG.md is missing a '## [${version}]' heading."
     echo "      A heading like '## ${version}' (no brackets) will NOT match — publish-release will fail."
     exit 1
   fi

   If the check fails, fix the heading or generate the section first:

   • For addon packages (native C++): run /qv-addon-changelog
   • For SDK pod packages (TypeScript): run /qv-sdk-changelog

Step 2: Confirm with user

Display a summary and ask for confirmation before proceeding:

Release summary:
  Package: <package>
  Version: <version>
  Branch:  release-<package>-<version>
  Target:  NPM (latest tag)

Proceed? (y/n)

Step 3: Create release branch

1. Ensure we're on the base branch and up to date:

   git checkout <base-branch>
   git pull origin <base-branch>

   Where <base-branch> is determined in Step 1 (main for new releases, release-<package>-<base-version> for patches).
2. Create the release branch:

   git checkout -b release-<package>-<version>

3. Push the release branch to remote (required for workflow dispatch to find the ref):

   git push origin release-<package>-<version>

4. Trigger the release workflow manually:

   gh workflow run "on-merge-<package>.yml" --repo tetherto/qvac --ref release-<package>-<version>

This workflow:

• Runs release-merge-guard (validates version bump + changelog)
• Builds prebuilds across platforms
• Publishes to NPM with latest tag
• Creates a GitHub release with tag <package>-v<version>

Step 4: Monitor CI pipeline

Use /loop to poll the pipeline status every 2 minutes:

/loop 2m Check the CI pipeline status for the release branch release-<package>-<version>. Run: gh run list --branch release-<package>-<version> --limit 5. If all runs completed successfully, report SUCCESS and stop. If any run failed, report the failure details. If still running, report progress.