Skip to content

RELEASING.md

Latest commit

 

History

History
78 lines (52 loc) · 8.49 KB

RELEASING.md

File metadata and controls

78 lines (52 loc) · 8.49 KB
Raw

Releasing Intent Runtime

Pushing a version tag starts the release pipeline. A matching stable V2 version, a passing CI matrix, and package checks are enforced by automation. No manually maintained acceptance run IDs or hashes are required.

One-time publisher setup

Use npm trusted publishing for this GitHub repository's .github/workflows/publish.yml, including the npm-release environment if configured on the npm publisher. The job requests id-token: write; publication uses provenance. The setup must match the npm package, repository, workflow filename and environment exactly. See npm trusted publishers.

Open the package settings as a package maintainer, find Trusted Publisher, and select GitHub Actions:

npm field Value for this repository
Package @devcodex/intent-runtime
Organization or user devcodex-labs
Repository intent-runtime
Workflow filename publish.yml — filename only, without .github/workflows/
Environment name npm-release — the current publishing job always uses this environment
Allowed actions Allow direct npm publish; staged publishing alone does not match this workflow

Save the publisher. No new npm token secret is required for this OIDC path. The current job already uses a GitHub-hosted Ubuntu runner, id-token: write, Node 24, the public npm registry, and --provenance. Trusted publishing requires Node >=22.14.0 and npm >=11.5.1; check the runner's npm version if troubleshooting. Separate npm dist-tag permission is unnecessary for the current workflow, which sets the initial default tag through publication and does not run npm dist-tag.

After configuration, the reviewed stable tag triggers validation and publication automatically. Confirm the publish job and registry-install verification both succeed. A local unauthenticated npm trust list returning 401 cannot confirm or disprove the GitHub OIDC configuration. Do not change package publishing-access policy or delete an existing token merely to inspect this setup.

An NPM_TOKEN repository/environment secret is supported as an alternative for an appropriately authorized npm token. An empty GitHub secret list alone does not establish whether trusted publishing is configured. Never treat a dry run as proof of publication authority.

GitHub Pages must use GitHub Actions as its source. The docs workflow deploys to the github-pages environment. Its deployment rules must allow main for manual documentation updates and the v2.* tag pattern for V2 releases. The version guard still restricts publication to a matching stable V2 tag. Environment protection settings remain part of the repository's deployment configuration.

Prepare and tag

  1. Update the version in both package.json and the root package entries in package-lock.json. Add a matching ## 2.x.y section to CHANGELOG.md; its body becomes the GitHub Release notes. Do not change result schemaVersion just because the npm package version changes.
  2. Review the current public API, upgrade instructions and examples. Run npm ci, npm run typecheck, npm run lint, npm test, npm run test:release, and npm run check:package. For documentation, run npm --prefix website ci, npm run docs:check, and npm run docs:build.
  3. Commit and push the reviewed source. Tag that exact commit, then push the tag. For version 2.0.1:
git tag v2.0.1
git push origin v2.0.1

The version guard rejects prereleases, mismatching tags, and inconsistent lock metadata. Tags outside the supported stable V2 line do not publish.

What runs automatically

  1. Validate package version, lock identity, tag, and authored release notes.

  2. Run the reusable CI workflow: quality/schema checks, documentation checks/build, and runtime/package checks on Linux, Windows and macOS with Node 20.0.0 and 24.x.

  3. Build and test a fresh tarball. Upload that exact tarball and SHA256SUMS before publication.

  4. Query the npm registry. A missing version may publish; an existing version may only resume if its name, version and SHA-512 integrity match the verified tarball. Registry errors are failures, not permission to publish.

  5. Publish the verified tarball with public access and provenance when needed.

  6. Verify registry integrity and latest. In two empty directories, install the exact version and the ordinary unversioned package from npm. Check installed version/integrity, root/API/MCP imports, worker entry, and both CLI versions. No separate schema-dsl install is performed.

    npm can accept a publication while the package is still processing. The registry verifier allows about five minutes for the exact version and latest to appear. The installed-entry probe also runs during pre-publication package checks, using the same constructor and CLI checks as registry verification.

  7. Create or resume the GitHub Release with the authored changelog section and package assets.

  8. Build and deploy the documentation from the same release commit, by directly calling the reusable docs workflow. This does not depend on events generated by GITHUB_TOKEN triggering another workflow.

The workflow is successful only after these stages pass. Controlled test executors verify contracts and integration; they do not certify model accuracy. Real-provider and client checks remain useful evidence for changes that affect recognition and protocol behavior.

Recover an interrupted release

First identify the last successful stage and retain the original run's npm-package artifact. npm versions are immutable; never move an existing release tag or try to replace published bytes.

Failure point Recovery
Before npm publication Fix the failure. If source changes, commit and review a new candidate; do not move a tag already associated with a published version.
npm succeeded, registry check failed Check registry availability, version, integrity and latest. Re-run the failed job from the same commit. It skips publication only when the rebuilt artifact matches the published integrity; any mismatch stops for investigation.
npm and verification succeeded, GitHub Release failed Re-run failed jobs in the original run. The release job downloads the original tarball, updates the authored notes and resumes asset upload. Do not re-publish npm.
Release succeeded, docs failed Re-run the failed docs job in the original run. It checks out the exact release SHA. Confirm the site after deployment.
A different artifact already owns the version Stop. Investigate which bytes and commit were published. Never bypass the integrity comparison; fix forward with a new patch version when source changes are needed.

For the first V2 release, do not point latest back to the incompatible abandoned major as an automatic recovery action. Resolve defects with a reviewed V2 patch. A genuine distribution failure must be reported with its actual registry and workflow state.

If a defect is confined to an unpublished maintainer verification script, fix and test that script on main without changing the published package or tag. Verify the original run's downloaded tarball against the registry with the corrected script. Only after that verification succeeds, resume the GitHub Release using the original assets and authored notes, and dispatch Deploy Docs on the existing release tag. Record the failed run and the separate recovery evidence; do not describe the original run as successful.

Documentation outside a package release

For a reviewed documentation fix already on main, run the Deploy Docs workflow manually on main. It verifies the deployment SHA before building. Check the live installation page, quick start, MCP/Codex guides, navigation and README links after deployment; a green build alone does not establish that users see the updated site.

English is the default language at the existing root URLs; Chinese is available under /zh/. Check both language selectors and corresponding pages, the two search indices, localized scenario downloads, and native search focus recovery. Sources live under website/content/en and website/content/zh; shared assets stay in website/content/public. Preserve old Chinese fragment aliases on default English pages when moving headings.

Reference: GitHub package publishing, reusable workflows.