Release process

Versioning

• Language / spec: current is v0.5 in docs/spec/v0.5.md (split across v0.5-*.md) with version index in docs/spec/versions.md (v0.1–v0.4 remain published).
• Historical visibility: prior language versions remain published and browsable; do not delete old spec files.
• AST schema: keep versioned schema artifacts together (schemas/signalql-ast-v0.1.schema.json … schemas/signalql-ast-v0.5.schema.json).
• Scope sync: spec, scope, and schema must be updated together per language version.
• npm packages (@signalql/*): use semver. Tag releases as compiler-v0.1.x or unified v0.1.x per team preference; document the mapping in the GitHub release notes.

Checklist for a public release

1. npm test and npm run build (includes docs site) pass on main.
2. Update any version constants in packages if publishing to npm.
3. Verify package contents before publishing:
   • npm pack --dry-run -w @signalql/compiler
   • npm pack --dry-run -w @signalql/parser
   • npm pack --dry-run -w @signalql/sdk
   • npm pack --dry-run -w @signalql/adapters
   • npm pack --dry-run -w @signalql/cli
   • npm pack --dry-run -w @signalql/mcp
4. Publish packages in dependency order:
   • npm publish -w @signalql/compiler --access public
   • npm publish -w @signalql/parser --access public
   • npm publish -w @signalql/sdk --access public
   • npm publish -w @signalql/adapters --access public
   • npm publish -w @signalql/cli --access public
   • npm publish -w @signalql/mcp --access public
5. Do not publish @signalql/playground; it is a private local app, not a package API.
6. Tag the repo from clean CI or a maintainer machine after packages are published.
7. Deploy docs: build artifact is docs/.vitepress/dist — publish to signalql.org hosting (GitHub Pages, Cloudflare Pages, etc.) per .github/workflows/docs.yml.
8. Announce with pointers to spec, local playground instructions, CLI package, and MCP — avoid duplicating full prose; link canonical docs.

GitHub ↔ site sync

The docs site is generated only from the docs/ tree in this repository. Deploying the VitePress build keeps GitHub and signalql.org aligned; do not hand-edit production HTML outside this repo.

v0.2 rollout order

1. Publish versions index and v0.2 as current.
2. Finalize v0.2 spec/scope and non-goal boundaries.
3. Update homepage/README/why positioning.
4. Ship AST/parser/compiler + schema v0.2 support.
5. Align MCP and query API contract docs.
6. Run tests/docs build and release readiness checks.