Publishing

Releases are created manually through the Release Dispatch GitHub Actions workflow. A push by itself does not publish a package.

Package contents

package.json#files includes lib/ and excludes source maps. The package therefore contains six generated files across two exports:

The archive also includes package.json, README.md, and LICENSE, which npm includes as package metadata and standard documentation. Source files, tests, and the remaining documentation are not published.

Inspect the archive before release:

npm run build
npm pack --dry-run

Verify both module formats and both exports. The middleware checks require the optional hono peer dependency, which is installed for development in this repository.

node -e "import('./lib/index.min.mjs').then(m => console.log(Object.keys(m)))"
node -e "console.log(Object.keys(require('./lib/index.min.cjs')))"
node -e "import('./lib/middlewares.min.mjs').then(m => console.log(Object.keys(m)))"
node -e "console.log(Object.keys(require('./lib/middlewares.min.cjs')))"

Versioning

The project follows Semantic Versioning for the public surface exported from src/index.ts and src/middlewares/index.ts.

Behavioral contracts matter too. Changing whether a capability degrades or throws can require a major release even when the TypeScript signature is unchanged.

Release preparation

Run the complete local checks:

npm test
npm run build
npm run build:docs
npm run build:docs:book
npm pack --dry-run

Then prepare the release documentation:

1. Add docs/release-notes/<version>.md using the nearest release as the structural reference.
2. Add or update docs/changes-log/YYYY-MM-DD.md with the implementation rationale and verification.
3. Move relevant [Unreleased] entries in CHANGELOG.md under the new version.
4. Link the release notes and changes log from docs/SUMMARY.md.

Release notes start with # Release Notes and ## Version <x.y.z>. Use only the sections relevant to the release:

Run the release

In GitHub, select Actions → Release Dispatch → Run workflow and provide the major, minor, and patch values.

The workflow performs secret detection, builds the package, generates documentation, runs tests and coverage, publishes to GitHub Packages, creates a GitHub release, and publishes the documentation site when the repository is public. The workflow stamps the requested version during publishing; do not add a nonexistent local release command.

Registry and secrets

publishConfig targets GitHub Packages with access: restricted. Repository visibility does not automatically change package visibility or permissions. Changing the publishing registry or access policy is a separate release decision.

The workflows require these repository secrets:

GitHub Actions supplies GITHUB_TOKEN for repository-scoped release operations.

Branch workflows

• Pushes to feature/** and hotfix/** run the feature validation workflow.
• Pushes to master run the main build, documentation, and test workflow.
• Neither branch workflow publishes a package.