This guide is for teams treating SQLQueryHelperjs as a released operational dependency, not only as a development library.
What A Good Release Should Contain
A production-grade release should ship more than a version bump.
reviewed source changes
updated engine documentation when capability boundaries moved
benchmark snapshot updates when performance-sensitive behavior changed
tested runtime behavior for the engines affected by the release
a changelog or release summary that explains risk and scope
Recommended Release Checklist
Before publishing a new package version, verify:
version metadata is correct
typecheck, build, tests, and docs generation all pass
benchmark data is current when behavior or performance-sensitive paths changed
engine guides and DATABASE_ENGINE.md reflect the actual runtime contract
npm package contents were checked with a dry run after the build-backed prepack step produced dist/
release notes summarize engine impact, compatibility impact, and operational risk
Merge Gates
The repository should treat GitHub Actions validation as the default merge gate.
run typecheck, build, tests, and docs generation in CI for pull requests
keep job names stable so branch protection can mark them as required
enable live-engine validation for PostgreSQL and MySQL when merge confidence depends on runtime behavior, not only mocked tests
treat required checks as part of the release contract, not as optional repository hygiene
For this repository, the stable required checks are:
CI / quality
CI / integration
That split makes it obvious whether a failure came from static quality gates or live database execution.
The integration job includes explicit readiness checks for PostgreSQL and MySQL before running the live test slice.
For MySQL-backed CI runs, the workflow also enables log_bin_trust_function_creators=1 in the ephemeral service container so trigger and routine integration tests can run without requiring the application test user to hold SUPER.
Release Benchmark Publication
The repository should treat benchmark publication as a release workflow, not as a required pull-request gate.
use the Release Benchmarks workflow to run cross-engine benchmarks with service containers
upload latest-results.* and versioned history files as workflow artifacts
publish results.* and comparison.* as GitHub release assets when the workflow runs from a release event
include the regression summary in the release notes when a previous benchmark baseline exists
When preparing an upcoming release manually, the workflow can accept a version override so the next benchmark baseline can be generated intentionally.
Automated npm Publication
The repository can publish to npm automatically, but only from main.
use the Publish NPM workflow triggered from the successful CI workflow on main
never publish from pull requests, feature branches, or ad hoc branch pushes
skip publication when the package version already exists on npm
require an NPM_TOKEN repository secret for publication
store that secret in GitHub under Settings > Secrets and variables > Actions
keep the secret name exactly as NPM_TOKEN
This keeps npm publication tied to the merge result on main, which is the only branch that should represent releasable state.
Engine-Aware Release Review
Do not review releases as if all engines are identical.
if PostgreSQL orchestration changed, review dependency depth and destructive behavior
if MySQL mutation behavior changed, review emulated returning(...) paths and live tests
if SQLite rebuild logic changed, review table-copy and trigger recreation behavior
The release question is not only “does it compile?” but also “did the engine contract move?”
Benchmark Handling
Use benchmark snapshots as directional release evidence.
refresh the benchmark snapshot when query builders, reflection planning, reflection execution, or engine adapters changed
compare the new snapshot with the previous released snapshot when possible
publish the machine-readable comparison artifact when benchmark history is available
mention notable regressions or improvements in release notes
Even before automated regression tracking exists, a release should leave a readable benchmark trail.
Documentation Handling
Documentation should be treated as part of the release artifact.
regenerate TypeDoc output
verify new editorial guides are linked from the documentation index
update engine wording when a feature moved from partial to full support, or from unsupported to supported
keep the compatibility matrix stricter than marketing wording
keep the documented plan-artifact and benchmark-history shapes aligned with actual emitted artifacts once implementation lands
keep the documented observability event schema aligned with the real emitted runtime events once tracing is implemented
Operational Risk Notes
Every non-trivial release should answer these questions:
did destructive behavior change?
did an emulated engine path change?
did dependency orchestration become broader or narrower?
did benchmark results move enough to matter operationally?
If the answer is yes, say so explicitly in the release summary.
Minimal Release Template
An effective release summary should include:
version number
engines affected
behavior changes
compatibility contract changes
benchmark notes
rollout cautions
That is enough for consumers to decide whether the upgrade is routine or needs staging rehearsal.