Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.md
index ccf1905a1..f1a25e4b6 100644
--- a/docs/14-migration-guide.md
+++ b/docs/14-migration-guide.md
@@ -745,14 +745,17 @@ fresh QR code.
### Upgrade Matrix
OpenWA 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 jumping
straight 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.md
index 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 the
GitHub 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.
```mermaid
flowchart LR
@@ -525,10 +529,10 @@ flowchart LR
V020[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]
end
subgraph 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 both
registries before applying any tag) and optionally `RELEASE_PAT` (authors the GitHub Release as a
user 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.md
git 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-only
git 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.ts
index 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];