Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(governance): align branch, label and risk docs with practice

Yudhi Armyndharis9cf3088948cc
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 04b4aab5f..fffab7ffd 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -2,9 +2,9 @@ name: CI
on:
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.yml
index 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.md
index 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 Request
Please 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.md
index 6389ad64c..c0e9e02bd 100644
--- a/docs/04-security-design.md
+++ b/docs/04-security-design.md
@@ -742,7 +742,7 @@ name: Security Scan
on:
push:
- branches: [main, develop]
+ branches: [main]
schedule:
- cron: '0 0 * * 1' # Weekly on Monday
diff --git a/docs/08-development-guidelines.md b/docs/08-development-guidelines.md
index 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 only
Examples:
-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:
```markdown
1. 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 standards
4. Write/update tests
5. 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.md
index 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 spec
diff --git a/docs/16-risk-management.md b/docs/16-risk-management.md
index b13a9cc44..a7d2e913b 100644
--- a/docs/16-risk-management.md
+++ b/docs/16-risk-management.md
@@ -270,7 +270,7 @@ flowchart TB
R --> 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 TB
3. **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.md
index 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 only
Examples:
-- 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 Channels
diff --git a/package.json b/package.json
index 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.ts
new file mode 100644
index 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([]);
+ });
+});