# Contributing to Wajeeh BI / BlueDXP Welcome. This repository powers the **BlueDXP platform** (Wajeeh BI brand) and its **Integrated Management System** (ISO 9001 / 14001 / 45001 / 27001 aligned). Read this entire file before your first commit — there is one mandatory rule that will reject your commit if you skip it. --- ## TL;DR for new developers ```bash git clone https://github.com/balbayaty/wajeeh-bi-bluedxp.git cd wajeeh-bi-bluedxp npm ci pwsh scripts/install-git-hooks.ps1 # installs the IMS pre-commit hook cp .env.example .env.local # then fill in your local values npm run smoke:ci # confirms your environment can build ``` If `npm run smoke:ci` passes, you have a working dev environment. --- ## The one rule that will reject your commit This repository enforces **`.cursor/rules/keep-ims-manual-in-sync.mdc`** via a local Git pre-commit hook (installed by `scripts/install-git-hooks.ps1`). If you stage **any file matching the in-scope globs** without also staging `platform-architecture-and-ims-sops.html`, your commit is rejected. In-scope globs (mirrors `.git/hooks/pre-commit` lines 38–47): ``` api/**/*.js api/**/*.ts api/_lib/** *.html vercel.json package.json lib/** app/** components/** types/** middleware/** ``` Out-of-scope exceptions (handled by the same hook): ``` scripts/smoke-* *test* *spec* .gateway-inspect/* *.css ``` ### Why the rule exists ISO 9001 §7.5.3 (Control of documented information) and ISO 27001 A.5.33 (Protection of records) require that every change to a controlled asset is identifiable, retrievable and reversible. The IMS manual is the controlled asset. Git history is the audit trail. If the manual lags behind the code, an auditor cannot trust either. ### How to satisfy the rule (correct workflow) 1. Make your code change. 2. Open `platform-architecture-and-ims-sops.html` and update the relevant data array (`MODULES`, `INTEGRATIONS`, `ROLES`, `SOPS`, `IMS`, `RISKS`, etc. — see the section comments inside the file). 3. Bump `const VERSION` (semver: patch for typos, minor for new features / policy expansion, major for breaking process changes). 4. Add an entry to the top of `const CHANGELOG` with `v`, `date`, `author` and a `changes:` array describing what shifted and **why**. 5. Run `node scripts/update-manual-revisions.js` to refresh `manual-revisions.json` (the manual reads this at runtime to render its "Document Control & Git Trail" panel). 6. Stage everything together: ```bash git add git add platform-architecture-and-ims-sops.html manual-revisions.json git commit -m "feat(): " ``` ### Override (use sparingly, almost never) ```powershell $env:SKIP_IMS_CHECK = "1"; git commit ... ``` ```bash SKIP_IMS_CHECK=1 git commit ... ``` You **must** explain _why_ in the commit footer. Every override is visible in the audit log via `git log --grep='SKIP_IMS_CHECK'`. --- ## Branching & PR workflow - `main` is the deploy branch. Every push to `main` triggers `.github/workflows/deploy-vercel.yml` which runs `npm run smoke:ci`, deploys to Vercel and curls the smoke endpoints on `https://wajeeh.app`. - Open all work as a feature branch off `main`: `feat/`, `fix/`, `docs/`, `chore/`. - Open a PR using the template (`.github/PULL_REQUEST_TEMPLATE.md`). The template asks the IMS-relevant questions every PR must answer. - A reviewer named in `.github/CODEOWNERS` is auto-requested for any change to a critical path (security, IMS manual, deploy workflow, etc.). --- ## Commit message convention We follow a relaxed Conventional-Commits style: ``` ():