Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(governance): align branch, label and risk docs with practice
Yudhi Armyndharis9cf3088948cc
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 04b4aab5f..fffab7ffd 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -2,9 +2,9 @@ name: CIon:push:- branches: [main, develop]+ branches: [main]pull_request:- branches: [main, develop]+ branches: [main]env:NODE_VERSION: '22'diff --git a/.github/workflows/sdk-ci.yml b/.github/workflows/sdk-ci.ymlindex 429059d8c..65e6fd5a8 100644--- a/.github/workflows/sdk-ci.yml+++ b/.github/workflows/sdk-ci.yml@@ -6,7 +6,7 @@ name: SDK CI# dual-format packaging smoke test (require() + import() both consumable).on:push:- branches: [main, develop]+ branches: [main]paths:['sdk/**',@@ -17,7 +17,7 @@ on:'src/engine/interfaces/whatsapp-engine.interface.ts',]pull_request:- branches: [main, develop]+ branches: [main]paths:['sdk/**',diff --git a/README.md b/README.mdindex 68f871087..8ea62494a 100644--- a/README.md+++ b/README.md@@ -486,9 +486,9 @@ Comprehensive documentation is available in the `docs/` folder:We welcome contributions! Here's how to get started:1. **Fork** the repository-2. **Create** your feature branch (`git checkout -b feature/amazing-feature`)+2. **Create** your feature branch (`git checkout -b feat/amazing-feature`)3. **Commit** your changes (`git commit -m 'Add amazing feature'`)-4. **Push** to the branch (`git push origin feature/amazing-feature`)+4. **Push** to the branch (`git push origin feat/amazing-feature`)5. **Open** a Pull RequestPlease read our [Development Guidelines](./docs/08-development-guidelines.md) for coding standards and best practices.diff --git a/docs/04-security-design.md b/docs/04-security-design.mdindex 6389ad64c..c0e9e02bd 100644--- a/docs/04-security-design.md+++ b/docs/04-security-design.md@@ -742,7 +742,7 @@ name: Security Scanon:push:- branches: [main, develop]+ branches: [main]schedule:- cron: '0 0 * * 1' # Weekly on Mondaydiff --git a/docs/08-development-guidelines.md b/docs/08-development-guidelines.mdindex 5023ed2c5..ecf047686 100644--- a/docs/08-development-guidelines.md+++ b/docs/08-development-guidelines.md@@ -306,47 +306,24 @@ new module is the standard template above: declare `exports` and let consumers `### Branch Strategy-```mermaid-gitGraph- commit id: "initial"- branch develop- commit id: "setup"- branch feature/session-api- commit id: "session controller"- commit id: "session service"- checkout develop- merge feature/session-api- branch feature/webhook- commit id: "webhook impl"- checkout develop- merge feature/webhook- checkout main- merge develop tag: "v1.0.0"- checkout develop- branch hotfix/bug-fix- commit id: "fix bug"- checkout main- merge hotfix/bug-fix tag: "v1.0.1"- checkout develop- merge hotfix/bug-fix-```+`main` is the only long-lived branch. Each change is made on a short-lived branch cut from `main`,+opened as a pull request against `main`, and merged with a merge commit once CI passes. Releases are+tagged from `main`; see [15.7 Cutting a Release](./15-project-roadmap.md#157-cutting-a-release).### Branch Naming```-main # Production-ready code-develop # Integration branch-feature/* # New features-bugfix/* # Bug fixes-hotfix/* # Production hotfixes-release/* # Release preparation+fix/* # Bug fixes+feat/* # New features+docs/* # Documentation only+chore/* # Tooling, dependencies, release housekeeping+refactor/* # Restructuring without a behavior change+test/* # Tests onlyExamples:-feature/session-management-feature/webhook-retry-bugfix/qr-code-timeout-hotfix/security-patch-release/1.0.0+fix/qr-code-timeout+feat/webhook-retry+docs/update-api-reference```### Commit Message Convention@@ -1176,13 +1153,13 @@ services:```markdown1. Fork the repository-2. Create feature branch: `git checkout -b feature/amazing-feature`+2. Create feature branch: `git checkout -b feat/amazing-feature`3. Make changes following our coding standards4. Write/update tests5. Run linter: `npm run lint`6. Run tests: `npm test`7. Commit: `git commit -m 'feat(scope): add amazing feature'`-8. Push: `git push origin feature/amazing-feature`+8. Push: `git push origin feat/amazing-feature`9. Open Pull Request````diff --git a/docs/10-devops-infrastructure.md b/docs/10-devops-infrastructure.mdindex efc5514ff..c6e69db7b 100644--- a/docs/10-devops-infrastructure.md+++ b/docs/10-devops-infrastructure.md@@ -251,9 +251,9 @@ an illustrative design sketch; the chart is the authoritative artifact.### GitHub Actions Workflow-`.github/workflows/ci.yml` (`name: CI`) runs on pushes and pull requests targeting `main` /-`develop`. It is **integration only** — no job deploys anywhere. The final job publishes branch and-SHA image tags to GHCR; `latest` is deliberately not set there and moves only through the separate,+`.github/workflows/ci.yml` (`name: CI`) runs on pushes and pull requests targeting `main`. It is+**integration only** — no job deploys anywhere. The final job publishes branch and SHA image+tags to GHCR; `latest` is deliberately not set there and moves only through the separate,boot-smoke-gated release workflow.The per-job step lists live in [docs/09 §9.6](./09-testing-strategy.md#96-ci-checks), which a specdiff --git a/docs/16-risk-management.md b/docs/16-risk-management.mdindex b13a9cc44..a7d2e913b 100644--- a/docs/16-risk-management.md+++ b/docs/16-risk-management.md@@ -270,7 +270,7 @@ flowchart TBR --> M3[Automation]R --> M4[Contributor onboarding]- M1 --> A1[Active Discord/forum]+ M1 --> A1[GitHub Discussions]M2 --> A2[Comprehensive docs]M3 --> A3[CI/CD automation]M4 --> A4[Contributing guide]@@ -291,12 +291,12 @@ flowchart TB3. **Community Building**- Recognize contributors- Good first issues- - Mentorship program+ - GitHub Discussions for questions and design talk-4. **Multiple Maintainers**- - Bus factor > 1- - Clear ownership areas- - Succession planning+4. **Bus Factor**+ - One maintainer today; a bus factor of 1 is the open risk+ - The docs, CI gates and tag-driven releases above are what let someone else pick the project up+ - Additional maintainers, ownership areas and succession planning are not in place yet---@@ -422,6 +422,8 @@ flowchart TB### Weekly Risk Review+Optional template: the project does not run this review on a schedule.+```markdown## Weekly Risk Review Template@@ -517,7 +519,8 @@ Hour 8-24:### Access- [ ] GitHub owner transfer-- [ ] npm publish rights+- [ ] Repository secrets: `DOCKERHUB_USERNAME`/`DOCKERHUB_TOKEN`, `RELEASE_PAT`, `MAVEN_CENTRAL_USERNAME`/`MAVEN_CENTRAL_PASSWORD`, `GPG_PRIVATE_KEY`/`GPG_PASSPHRASE`, `PHP_SDK_SPLIT_TOKEN`+- [ ] Registries: Docker Hub `rmyndharis/openwa`, npm `@rmyndharis/openwa` and PyPI `rmyndharis-openwa` (trusted publishers bound to this repository), Maven Central `com.rmyndharis`, Packagist `rmyndharis/openwa` via the `rmyndharis/openwa-php` mirror; GHCR images and Go module tags follow the GitHub repository- [ ] Domain ownership- [ ] Cloud accounts@@ -716,6 +719,8 @@ flowchart LR### Weekly Risk Report Template+Optional template: the project does not run this review on a schedule.+```markdown## Weekly Risk Report - Week XX@@ -768,17 +773,6 @@ flowchart LR| R007 | Rate Limiting | High | Medium | 🟡 Medium | Partially mitigated || R008 | Data Loss | Low | High | 🟡 Medium | Mitigated |-### Risk Trend--```mermaid-xychart-beta- title "Risk Trend Over Time"- x-axis [Jan, Feb, Mar, Apr, May, Jun]- y-axis "Risk Score" 0 --> 100- bar [65, 55, 45, 40, 35, 30]- line [65, 55, 45, 40, 35, 30]-```----<div align="center">diff --git a/docs/20-community-guidelines.md b/docs/20-community-guidelines.mdindex bcbe788ff..a938a32fa 100644--- a/docs/20-community-guidelines.md+++ b/docs/20-community-guidelines.md@@ -75,16 +75,16 @@ npm run dev### Branch Naming```-feature/ - New features-bugfix/ - Bug fixes-hotfix/ - Critical production fixes-docs/ - Documentation changes-refactor/ - Code refactoring-test/ - Test additions/modifications+fix/ - Bug fixes+feat/ - New features+docs/ - Documentation only+chore/ - Tooling, dependencies, release housekeeping+refactor/ - Restructuring without a behavior change+test/ - Tests onlyExamples:-- feature/add-group-management-- bugfix/fix-qr-timeout+- fix/qr-timeout+- feat/group-management- docs/update-api-reference- refactor/session-manager```@@ -163,7 +163,7 @@ Closes #```3. **Review Process:**- - CI (`.github/workflows/ci.yml`) runs on every pull request targeting `main` or `develop`+ - CI (`.github/workflows/ci.yml`) runs on every pull request targeting `main`- A maintainer reviews the change and merges it- Address review comments- Keep the PR focused on one logical change@@ -293,6 +293,16 @@ not supported on whatsapp-web.js, the default engine.| `design` | Architecture / design discussion || `engine:baileys` | Baileys engine specific || `upstream-blocked` | Blocked on upstream library/WhatsApp behavior; no OpenWA-side fix |+| `release` | Release / version PR |+| `dependencies` | Pull requests that update a dependency file |+| `dashboard` | Dashboard (React) changes |+| `ci` | CI and GitHub Actions workflow changes |+| `docker` | Docker image and container changes |+| `github_actions` | Pull requests that update GitHub Actions code |+| `javascript` | Pull requests that update javascript code |++`.github/dependabot.yml` applies `dependencies`, `dashboard`, `ci` and `docker`; `github_actions` and+`javascript` are Dependabot defaults from before it set explicit labels.## 20.4 Community Channelsdiff --git a/package.json b/package.jsonindex 00099a13c..b5843cceb 100644--- a/package.json+++ b/package.json@@ -42,7 +42,7 @@"lint:fix": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix","test": "jest","test:scripts": "node --test scripts/postinstall.spec.js scripts/patch-wwebjs-newsletter-preview.spec.js scripts/patch-wwebjs-status.spec.js scripts/patch-wwebjs-ready-sync.spec.js scripts/patch-wwebjs-participant-arity.spec.js scripts/patch-wwebjs-block.spec.js scripts/patch-wwebjs-group-description.spec.js scripts/patch-wwebjs-media-id.spec.js scripts/patch-wwebjs-send-error.spec.js scripts/patch-baileys-appstate.spec.js scripts/patch-baileys-newsletter-create.spec.js scripts/dockerfile-patchers.spec.js scripts/check-upstream-surface.spec.mjs scripts/check-sdk-docs.spec.mjs scripts/check-audit.spec.mjs scripts/check-contract-shapes.spec.mjs scripts/check-sdk-coverage.spec.mjs scripts/cli-entrypoint-guard.spec.mjs",- "test:docs": "jest src/common/changelog-sections.spec.ts src/common/ci-privilege-gate.spec.ts src/common/docs-ci-jobs.spec.ts src/common/docs-coverage-policy.spec.ts src/common/docs-metrics-list.spec.ts src/common/docs-next-version.spec.ts src/common/docs-sdk-rate-limit.spec.ts src/common/openapi/docs-06-contract.spec.ts src/common/test-lane-partition.spec.ts src/config/docs-env-example.spec.ts src/config/openapi-contract.spec.ts src/config/openapi-export-pins.spec.ts src/config/wa-web-version-example-pin.spec.ts src/engine/docs-29-counts.spec.ts src/engine/docs-27-backfill-engine.spec.ts src/engine/engine-inventory-parity.spec.ts src/engine/engine-parity.spec.ts src/engine/inventory-mapping-direction.spec.ts src/engine/adapters/baileys-voice-waveform.spec.ts src/engine/adapters/wwebjs-newsletter-preview.spec.ts src/modules/audit/audit-coverage.spec.ts src/modules/auth/global-route-fence-coverage.spec.ts src/modules/auth/query-session-scope-coverage.spec.ts src/modules/docker/compose-network.spec.ts src/modules/queue/bull-board-mount-coverage.spec.ts src/common/release-gate-parity.spec.ts src/database/migrations/__tests__/migration-drift.spec.ts --testPathIgnorePatterns=/node_modules/",+ "test:docs": "jest src/common/changelog-sections.spec.ts src/common/ci-privilege-gate.spec.ts src/common/docs-ci-jobs.spec.ts src/common/docs-coverage-policy.spec.ts src/common/docs-metrics-list.spec.ts src/common/docs-next-version.spec.ts src/common/docs-sdk-rate-limit.spec.ts src/common/openapi/docs-06-contract.spec.ts src/common/test-lane-partition.spec.ts src/config/docs-env-example.spec.ts src/config/openapi-contract.spec.ts src/config/openapi-export-pins.spec.ts src/config/wa-web-version-example-pin.spec.ts src/engine/docs-29-counts.spec.ts src/engine/docs-27-backfill-engine.spec.ts src/engine/engine-inventory-parity.spec.ts src/engine/engine-parity.spec.ts src/engine/inventory-mapping-direction.spec.ts src/engine/adapters/baileys-voice-waveform.spec.ts src/engine/adapters/wwebjs-newsletter-preview.spec.ts src/modules/audit/audit-coverage.spec.ts src/modules/auth/global-route-fence-coverage.spec.ts src/modules/auth/query-session-scope-coverage.spec.ts src/modules/docker/compose-network.spec.ts src/modules/queue/bull-board-mount-coverage.spec.ts src/common/release-gate-parity.spec.ts src/database/migrations/__tests__/migration-drift.spec.ts src/common/docs-governance.spec.ts --testPathIgnorePatterns=/node_modules/","test:watch": "jest --watch","test:cov": "jest --coverage","test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",@@ -154,6 +154,7 @@"src/common/ci-privilege-gate\\.spec\\.ts$","src/common/release-gate-parity\\.spec\\.ts$","src/common/docs-ci-jobs\\.spec\\.ts$",+ "src/common/docs-governance\\.spec\\.ts$","src/common/docs-coverage-policy\\.spec\\.ts$","src/common/docs-metrics-list\\.spec\\.ts$","src/common/docs-next-version\\.spec\\.ts$",@@ -477,6 +478,7 @@"src/common/ci-privilege-gate\\.spec\\.ts$","src/common/release-gate-parity\\.spec\\.ts$","src/common/docs-ci-jobs\\.spec\\.ts$",+ "src/common/docs-governance\\.spec\\.ts$","src/common/docs-coverage-policy\\.spec\\.ts$","src/common/docs-metrics-list\\.spec\\.ts$","src/common/docs-next-version\\.spec\\.ts$",diff --git a/src/common/docs-governance.spec.ts b/src/common/docs-governance.spec.tsnew file mode 100644index 000000000..5fc6c2356--- /dev/null+++ b/src/common/docs-governance.spec.ts@@ -0,0 +1,70 @@+import { readdirSync, readFileSync } from 'node:fs';+import { join } from 'node:path';+import * as yaml from 'js-yaml';++/**+ * The contributor docs restate the CI trigger branches and the repository label set by hand. Both+ * drifted: the docs and the workflows named a `develop` branch that never existed, and the label+ * table missed labels Dependabot applies to every dependency PR. These pin the hand-written copies+ * to the files that actually decide the behaviour.+ */++const root = join(__dirname, '..', '..');+const read = (...parts: string[]): string => readFileSync(join(root, ...parts), 'utf8');++function between(text: string, from: string, to: string): string {+ const start = text.indexOf(from);+ expect(start).toBeGreaterThanOrEqual(0);+ const end = text.indexOf(to, start + from.length);+ expect(end).toBeGreaterThan(start);+ return text.slice(start, end);+}++type Trigger = { branches?: string[] };+type Workflow = { on?: { push?: Trigger; pull_request?: Trigger } };++describe('governance docs match the repository', () => {+ it.each(['ci.yml', 'sdk-ci.yml'])('%s runs on main only', file => {+ const wf = yaml.load(read('.github', 'workflows', file)) as Workflow;+ expect(wf.on?.push?.branches).toEqual(['main']);+ expect(wf.on?.pull_request?.branches).toEqual(['main']);+ });++ it('keeps the recommended security workflow template on main only', () => {+ const template = between(read('docs/04-security-design.md'), '# .github/workflows/security.yml', '\n```');+ expect((yaml.load(template) as Workflow).on?.push?.branches).toEqual(['main']);+ });++ it.each([+ ['docs/08-development-guidelines.md', '## 8.4', '## 8.5'],+ ['docs/10-devops-infrastructure.md', '## 10.3', '## 10.4'],+ ['docs/20-community-guidelines.md', '## 20.2', '## 20.3'],+ ])('%s names main and no develop branch', (file, from, to) => {+ const section = between(read(file), from, to);+ expect(section).toContain('`main`');+ expect(section).not.toMatch(/\bdevelop\b/);+ });++ it('documents every label the repository applies automatically', () => {+ const dependabot = yaml.load(read('.github', 'dependabot.yml')) as { updates: Array<{ labels?: string[] }> };+ const templateDir = join(root, '.github', 'ISSUE_TEMPLATE');+ const templateLabels = readdirSync(templateDir)+ .filter(name => name.endsWith('.yml'))+ .flatMap(+ name => (yaml.load(readFileSync(join(templateDir, name), 'utf8')) as { labels?: string[] }).labels ?? [],+ );+ const applied = [...new Set([...dependabot.updates.flatMap(u => u.labels ?? []), ...templateLabels])];++ const documented = new Set<string>();+ for (const line of between(read('docs/20-community-guidelines.md'), '### Issue Labels', '## 20.4').split('\n')) {+ const cells = line.split('|').map(cell => cell.trim());+ const name = cells[1]?.match(/^`([^`]+)`$/);+ if (name) documented.add(name[1]);+ }++ // Guard both parsers: either one matching nothing would make the final check pass vacuously.+ expect(applied.length).toBeGreaterThanOrEqual(6);+ expect(documented.size).toBeGreaterThanOrEqual(20);+ expect(applied.filter(label => !documented.has(label))).toEqual([]);+ });+});