Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(roadmap): enforce the pre-1.0 versioning rule from 0.24.0
Yudhi Armyndharisd90e12c6db27
diff --git a/docs/14-migration-guide.md b/docs/14-migration-guide.mdindex ccf1905a1..f1a25e4b6 100644--- a/docs/14-migration-guide.md+++ b/docs/14-migration-guide.md@@ -745,14 +745,17 @@ fresh QR code.### Upgrade MatrixOpenWA is pre-1.0 — every release to date is on the `0.x` line. Under the project's SemVer 0.x policy a-breaking change bumps the **minor** (`0.10.x` → `0.11.0`) and everything else is a patch, so a minor bump-is the one that warrants reading the release notes closely.--| From | To | Migration Type | Downtime |-| --------------------- | ------------------- | ---------------------------------------------- | --------- |-| `0.x.y` | `0.x.z` (patch) | Pending migrations only | < 5 min |-| `0.x.y` | `0.(x+1).0` (minor) | Pending migrations + review the breaking notes | 5-15 min |-| Several releases back | Current | Same — the migration chain replays in order | 10-15 min |+breaking change, or anything the CHANGELOG files under **Upgrade notes (behavior changes)**, bumps the+**minor** (`0.10.x` → `0.11.0`) and everything else is a patch, so a minor bump is the+one that warrants reading the release notes closely. The rule holds from `0.24.0`: earlier patches did not+always follow it (`0.23.3` and `0.23.5` to `0.23.7` carried Upgrade notes; section 15.2 of docs/15 lists+every exception), so an upgrade across one of them needs its CHANGELOG notes read.++| From | To | Migration Type | Downtime |+| --------------------- | ------------------- | ---------------------------------------------------------------- | --------- |+| `0.x.y` | `0.x.z` (patch) | Pending migrations only | < 5 min |+| `0.x.y` | `0.(x+1).0` (minor) | Pending migrations + review the breaking notes and Upgrade notes | 5-15 min |+| Several releases back | Current | Same — the migration chain replays in order | 10-15 min |Upgrades are cumulative: migrations apply in order from wherever the schema currently sits, so jumpingstraight to the current release is supported. There is no required intermediate stop — but read every@@ -833,7 +836,7 @@ docker compose run --rm openwa-api npm run migration:run:prod| Release | Change | Action || -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |-| `0.23.8` | `POST /api/sessions/:sessionId/messages/send-product` passes the `message:sending` plugin gate (type `product`, input `{ chatId, productId, body }`); a rewritten `chatId` is ignored | Branch on `source`/`type` before reading send-DTO fields; a veto now answers `400` |+| `0.24.0` | `POST /api/sessions/:sessionId/messages/send-product` passes the `message:sending` plugin gate (type `product`, input `{ chatId, productId, body }`); a rewritten `chatId` is ignored | Branch on `source`/`type` before reading send-DTO fields; a veto now answers `400` || `0.23.6` | A media URL passed to a send route or to `POST /media/convert/voice` or `.../convert/video`, and the link preview of a text send, are fetched through the egress proxy of the session named in the request instead of leaving from the gateway's own address | Set `SESSION_PROXY_URL_FETCH=false` if a session proxy is a WhatsApp-only route that cannot reach arbitrary media hosts || `0.23.0` | Typed SDK clients: `markRead` and `subscribePresence` each take their own request type instead of the shared `MarkChatRequest`, which now serves `markUnread` alone | Go and Java: swap the type at both call sites. Typed Python: only at `markRead`, its `subscribePresence` body being structurally identical. JavaScript and PHP need no change; the wire body is unchanged || `0.22.0` | Baileys refuses a reply whose quoted id, or a forward whose `fromChatId`, does not name the addressed chat, with the `404` whatsapp-web.js already answered; leaving a group, unsubscribing from a channel and labelling a channel surface WhatsApp's refusal; membership requests for an id that is not a group are refused | Handle a refusal on those six calls, which previously answered `200` whatever happened |diff --git a/docs/15-project-roadmap.md b/docs/15-project-roadmap.mdindex ee1e3e646..f0a7b60d4 100644--- a/docs/15-project-roadmap.md+++ b/docs/15-project-roadmap.md@@ -40,8 +40,8 @@ timeline: Bundled Traefik removed: Bring-your-own reverse proxy- section v0.5.0-v0.12.x - Incremental Releases (Released)- Jun-Jul 2026 : Integration Fabric provisioning+ section v0.5.0-v0.23.x - Incremental Releases (Released)+ Jun-Sep 2026 : Integration Fabric provisioning: Java & Go SDKs: Live message edits: Chat kind discriminator & status store@@ -82,6 +82,7 @@ timeline| v0.10.x | Chat `kind` discriminator, 24-hour status store, Docker Hub dual-publish | ✅ Released || v0.11.0 | SDK poll / profile-picture / status-media coverage, security & reliability hardening | ✅ Released || v0.12.x | Session/engine decomposition (`EngineRegistry`), plugin lifecycle and configuration-precedence fixes | ✅ Released |+| v0.13+ | Incremental releases through v0.23.x; see `CHANGELOG.md` | ✅ Released || v1.0.0 | Enterprise Ready (K8s Operator, multi-tenant) | 📋 Planned |> SDK / docs-site / observability features are delivered **incrementally** as they're additive — they no@@ -136,12 +137,16 @@ follow the SemVer "major version zero" convention:- **PATCH (`0.2.x`)** — bug fixes **and** backward-compatible additions (new endpoints, optional fields,new opt-in features). The default for ongoing work.- **MINOR (`0.3.0`, `0.4.0`, …)** — **breaking changes** (removed/renamed fields, changed payload- semantics, deployment-topology changes). A breaking change does **not** stay in `0.2.x`.+ semantics, deployment-topology changes). A breaking change does **not** ship in a patch release,+ and neither does anything the CHANGELOG files under **Upgrade notes (behavior changes)**.- Every breaking change ships with a prominent **⚠️ callout + migration note** in the CHANGELOG and theGitHub release, because the version number alone won't fully signal it pre-1.0.-> Note: `0.2.8` shipped one breaking change (webhook `type` neutralization, #270) as a patch — that-> predates this policy and is documented with a migration note; the policy applies from `0.2.9` onward.+> Note: `0.1.7` and `0.2.2` carried Upgrade notes, and `0.2.8` shipped one breaking change (webhook+> `type` neutralization, #270) as a patch, all before this policy existed. Later patch releases did not hold to it either: `0.8.19`, `0.14.5` and `0.14.6`+> carried breaking entries, and `0.23.3`, `0.23.5`, `0.23.6` and `0.23.7` carried Upgrade notes. Each+> has its migration note in the CHANGELOG. The rule is enforced from `0.24.0`:+> `src/common/docs-governance.spec.ts` fails a patch release whose CHANGELOG section has either.## 15.3 Phase 1: MVP (Month 1-3)@@ -507,8 +512,7 @@ v0.1.0 Release Package:## 15.6 Future Roadmap (v0.3.0+)> **Note:** Version 0.1.0 is the initial stable release including all features from Phases 1-3.-> Versions 0.1.7 through 0.11.0 have since shipped (see the CHANGELOG); v1.0.0-> onward is forward-looking.+> Later versions have shipped since (see the CHANGELOG); v1.0.0 onward is forward-looking.```mermaidflowchart LR@@ -525,10 +529,10 @@ flowchart LRV020[v0.2.0 - i18n, Real-time Chats,<br/>Webhook Delivery-state & Hardening]end- subgraph v0.x["✅ Released (v0.3–v0.11)"]+ subgraph v0.x["✅ Released (v0.3-v0.23.x)"]V030[v0.3.0 - Engine Pluggability<br/>Baileys engine + plugin layer]V040[v0.4.0 - Single-Port Deployment<br/>Dashboard on API port, no bundled Traefik]- V011[v0.5.0-v0.12.x - Incremental releases<br/>see the CHANGELOG]+ V011[v0.5.0-v0.23.x - Incremental releases<br/>see the CHANGELOG]endsubgraph v1.x["v1.x Series - Enterprise"]@@ -638,9 +642,9 @@ architecture and design rationale):## 15.7 Cutting a Release-Releases are cut by a maintainer from `main`. There is no release branch and no release PR: the-version bump lands as a single commit on `main`, and pushing the tag hands everything else to-`.github/workflows/release.yml`.+Releases are cut by a maintainer from `main`. There is no long-lived release branch: the version+bump is a single commit on a short-lived `chore/release-<version>` branch, merged to `main` through a+PR, and pushing the tag from `main` hands everything else to `.github/workflows/release.yml`.### Before you start@@ -650,8 +654,9 @@ version bump lands as a single commit on `main`, and pushing the tag hands every- The release job needs `DOCKERHUB_USERNAME` / `DOCKERHUB_TOKEN` (promotion logs into bothregistries before applying any tag) and optionally `RELEASE_PAT` (authors the GitHub Release as auser rather than the bot). Check with `gh secret list`.-- Pick the version per [15.2](#152-version-numbering). Pre-1.0, a release containing **any**- breaking change is a MINOR — patch releases carry none.+- Pick the version per [15.2](#152-version-numbering). Pre-1.0, a release whose `[Unreleased]`+ section has **any** breaking entry or an **Upgrade notes** heading is a MINOR; patch releases+ carry neither.### The release commit@@ -699,10 +704,14 @@ cd dashboard && npm run lint && npm run typecheck && npm run i18n:check && npm r```bash# SECURITY.md only on a MINOR; the chart's own `version:` bumps a patch alongside `appVersion`.+git switch -c chore/release-<version>git add package.json package-lock.json openapi.json CHANGELOG.md charts/openwa/Chart.yaml SECURITY.mdgit commit -m "chore(release): v<version>"+git push origin chore/release-<version> # open the PR to main and merge it once CI is green++git switch main && git pull --ff-onlygit tag -a v<version> -m "v<version>"-git push origin main --follow-tags+git push origin v<version>```The tag must be annotated and `v`-prefixed; `release.yml` triggers on `v*` and refuses to proceed if@@ -800,7 +809,7 @@ build from source and tag the result with the published image name.| PostgreSQL stable | ✅ | ✅ Achieved | Internal || Webhook delivery rate | > 99% | ✅ Achieved | Internal || Test coverage | > 70% | ⚠️ line coverage sits well above the ratchet floors — `npm run test:cov` is the source of truth | Internal |-| GitHub stars | 100+ | 📋 Pending | External |+| GitHub stars | 100+ | ✅ Achieved | External |### Phase 3 Success Criteria@@ -810,9 +819,9 @@ build from source and tag the result with the published image name.| API response time (p95) | < 200ms | ✅ Achieved | Internal || Test coverage | > 80% | ⚠️ above the per-directory ratchet floors; see docs/09 §9.5 | Internal || Documentation coverage | 100% | ✅ 95%+ | Internal |-| Production users | 50+ | 📋 Pending | External |-| GitHub stars | 500+ | 📋 Pending | External |-| Community contributors | 5+ | 📋 Pending | External |+| Production users | 50+ | Not measured (no usage telemetry) | External |+| GitHub stars | 500+ | ✅ Achieved | External |+| Community contributors | 5+ | ✅ Achieved | External |---diff --git a/src/common/docs-governance.spec.ts b/src/common/docs-governance.spec.tsindex 143c2c15f..4664a386a 100644--- a/src/common/docs-governance.spec.ts+++ b/src/common/docs-governance.spec.ts@@ -20,6 +20,24 @@ function between(text: string, from: string, to: string): string {return text.slice(start, end);}+/**+ * Patch releases from `0.24.0` on whose CHANGELOG section carries a breaking entry or an Upgrade+ * notes heading. docs/15 section 15.2 reserves both for a MINOR; earlier patches that broke the rule+ * are listed there and stay out of scope. A breaking entry is matched in every spelling the file has+ * used: `**Breaking`, `**BREAKING` and an unbolded warning-sign `Breaking:`.+ */+function patchesCarryingBreakingChanges(changelog: string): string[] {+ return changelog.split(/^(?=## \[)/m).flatMap(block => {+ const version = /^## \[(\d+)\.(\d+)\.(\d+)\]/.exec(block);+ if (!version) return [];+ const [major, minor, patch] = version.slice(1).map(Number);+ const enforced = major > 0 || minor >= 24;+ return enforced && patch > 0 && /^### Upgrade notes|\*\*breaking|\u26a0\ufe0f?\s*\**\s*breaking/im.test(block)+ ? [version.slice(1).join('.')]+ : [];+ });+}+type Trigger = { branches?: string[] };type Workflow = { on?: { push?: Trigger; pull_request?: Trigger } };@@ -68,6 +86,34 @@ describe('governance docs match the repository', () => {expect(applied.filter(label => !documented.has(label))).toEqual([]);});+ it('keeps breaking entries and Upgrade notes out of patch releases', () => {+ expect(patchesCarryingBreakingChanges(read('CHANGELOG.md'))).toEqual([]);+ });++ // The operator-facing upgrade matrix restates the section 15.2 rule, so it has to name the same+ // triggers for a MINOR and admit the earlier patches that did not hold to it.+ it('states the docs/15 version rule in the docs/14 upgrade matrix', () => {+ expect(between(read('docs/15-project-roadmap.md'), '### Pre-1.0 policy', '## 15.3')).toMatch(+ /Upgrade notes \(behavior changes\)/,+ );+ const matrix = between(read('docs/14-migration-guide.md'), '### Upgrade Matrix', '\n| From');+ expect(matrix).toMatch(/breaking change, or anything the CHANGELOG files under \*\*Upgrade notes/);+ expect(matrix).toMatch(/`0\.24\.0`/);+ });++ it('flags a patch release that carries either', () => {+ const sample = [+ '## [Unreleased]\n### Upgrade notes (behavior changes)\n- pending',+ '## [0.24.4] - 2026-10-04\n### Changed\n- **BREAKING \u2014 single-port dashboard:** x',+ '## [0.24.3] - 2026-10-03\n### Removed\n- \u26a0\ufe0f Breaking: bundled extensions removed',+ '## [0.24.2] - 2026-10-02\n### Fixed\n- \u26a0\ufe0f **Breaking (API).** a route answers 400',+ '## [0.24.1] - 2026-10-01\n### Upgrade notes (behavior changes)\n- a default changed',+ '## [0.24.0] - 2026-09-30\n### Upgrade notes (behavior changes)\n- a MINOR may',+ '## [0.23.7] - 2026-09-25\n### Upgrade notes (behavior changes)\n- before the rule',+ ].join('\n');+ expect(patchesCarryingBreakingChanges(sample)).toEqual(['0.24.4', '0.24.3', '0.24.2', '0.24.1']);+ });+it('points the circular-dependency advice at the comment that explains the delegation', () => {const section = between(read('docs/08-development-guidelines.md'), '#### Circular Dependency', '\n#### ');const cited = /`(src\/[^`]+\.ts)`/.exec(section)?.[1];