Release Policy

active · applies to WATS toolkit · reviewed 2026-05-01

WATS uses semantic versioning across published workspace packages.

0.x development line

The 0.x line covers the public toolkit while it expands toward full WhatsApp parity.

• Patch bump: documentation fixes, test-only changes, non-behavioral repo hygiene, or bug fixes that do not change public contracts.
• Minor bump: any new public feature, endpoint family, package, CLI command, config schema field, standalone service route, persistence contract, or deployment artifact that defines supported behavior.
• Breaking changes are allowed, but they require a minor bump in 0.x and must be called out in CHANGELOG.md, release notes, migration docs when relevant, and the public API/reference docs.

Releases stay credential-free by default: no Meta, npm, GitHub release, package-registry, or container-registry secrets are required for local checks.

1.x stable line

1.0.0 ships only when WATS has a coherent, publishable WhatsApp operations surface:

• packages are publishable from dist, not source-only exports
• CI runs tests, type checks, package smoke tests, and docs checks
• Graph, webhook, routing, config, CLI onboarding, and standalone service are documented
• OpenAPI 3.1 exists for the standalone service
• remaining gaps are explicitly labeled as post-1.0, experimental, or unsupported

After 1.0.0:

• Patch bump: backward-compatible fixes and docs clarifications.
• Minor bump: backward-compatible public API additions.
• Major bump: breaking public contract changes.

Package policy

The root package is private. Published packages are scoped under @wats/*.

Publishable packages:

• @wats/types
• @wats/crypto
• @wats/graph
• @wats/core
• @wats/http
• @wats/internal-utils (published internal support, not stable application API)
• @wats/config
• @wats/service
• @wats/cli

Private packages:

• @wats/testing

@wats/internal-utils is published because @wats/config depends on it at runtime; keeping it private would make registry installs fail. It stays documented as internal.

@wats/testing is workspace-only and intentionally outside the public package version-alignment contract. It is never published, keeps workspace:* dependencies, and exists only to host consumer fixtures and policy checks. A workspace test enforces public-package version alignment while excluding it.

Publishable packages expose built dist artifacts via main, types, and exports — dist/index.js, dist/index.d.ts, and matching subpath files. Source-only ./src/*.ts exports are fine for the local Bun workspace, never for registry release.

Pre-release gates

Before publication:

bun run check-publish

check-publish runs typecheck, bun run build:packages, bun run pack:smoke, and the workspace-policy tests. pack:smoke verifies each package tarball contains package.json, dist/index.js, and dist/index.d.ts, and excludes source entrypoints, .env files, and node_modules. The docs site is built and deployed separately from site/.

Actual npm publish --access public requires a valid npm token and explicit operator authorization. Dry-run checks never publish, tag, or push.

Changelog policy

CHANGELOG.md is user-facing. Each release entry answers:

1. What changed?
2. What can users do now that they could not do before?
3. What changed in the public contract?
4. Which docs and parity rows changed?
5. Which known gaps remain?

One entry per feature. If review reopens a feature before release, amend the original entry in place.

Credential gate

Work that touches live Meta Graph endpoints requires explicit operator authorization and a documented secrets plan.

Allowed without credentials:

• unit tests
• MockTransport tests
• config parsing/validation
• OpenAPI generation
• local webhook signature tests with synthetic secrets
• docs and package smoke tests

Requires authorization:

• live message send
• live template/media/flow/calling/admin endpoint checks
• live webhook verification using real app secrets
• any operation that mutates WABA, phone-number, template, media, catalog, flow, or calling state

Release readiness checklist

Before tagging or pushing a release:

• working tree clean
• bun test green
• type checks green for all publishable packages
• package exports point at build output for publishable packages
• consumer fixtures import only through package specifiers
• README reflects actual shipped scope
• reference docs, guides, and parity matrix updated
• changelog entry written
• no secrets or credential values committed