Skip to content
Ordermatic Docs

Change Management Policy
Owner [Security Owner — to be named: founder/CTO]
Approved by [signatory]
Effective date [set on approval]
Review cadence Annual
Version 0.1 — DRAFT
TSC mapping CC8.1

1. Purpose

Section titled “1. Purpose”

Ensure that changes to the Ordermatic platform are reviewed, tested, and approved before reaching production, and that the path from code to production is restricted and auditable.

2. Branching & promotion model

Section titled “2. Branching & promotion model”

Code flows in one direction: feature branch → staging → main → production.

  • All work happens on a feature branch. Direct commits to staging or main are prohibited.
  • Changes merge into staging only via a pull request that passes the required CI checks (the non-bypassable automated gates). Review follows §3 — independent approval when a second engineer is available or the change is high-risk; documented self-review when operating solo.
  • Production images build from main. main is updated only by the automated promotion (.github/workflows/auto-deploy-main.yml), which fast-forwards main to a healthy, already-reviewed staging via a direct git push (not a PR merge). A human manually triggering that promotion (workflow_dispatch) is the production-release approval. The daily 2 AM cron runs a divergence check only — it never auto-promotes, and there is no automated release PR.
  • .github/workflows/promotion-guard.yml blocks any branch other than staging (or an explicitly hotfix-labeled PR) from reaching main.
  • Branch protection enforces this server-side via two staging rulesets: the automated gates (required CI checks; no one, including admins, can bypass) and the review rule (independent approval, admin-bypassable for the solo path in §3), plus restricted push (see ../branch-protection-proposal.md).

3. Required controls on every change

Section titled “3. Required controls on every change”
  • Automated gates (non-bypassable): every change opens a PR and must pass CodeQL, the supply-chain / dependency audit, tests, and the Changeset required check — enforced by the staging - automated gates ruleset that no one, including admins, can bypass. These are the primary, always-on control (CC8).
  • Independent human review: at least one approving review is required on staging whenever a second engineer is available, and is mandatory for higher-risk changes (customer ERP-write paths, authentication, database migrations). When the company is operating with a single developer, the author performs a documented self-review (checklist below) and may merge once the automated gates pass; that merge-without-second-review is recorded by GitHub (ruleset bypass log) as the defined solo-developer exception, with the separate manual production promotion (§2) as the compensating checkpoint. Independent review resumes automatically as the team grows (“Formal Code Review Process”).
  • Conventional commits: feat:, fix:, docs:, chore:, etc.
  • Database changes: schema migrations are generated by Drizzle from packages/db/src/schema/*.ts. Hand-written SQL migrations are prohibited.
  • ERP writes: any change that writes to a customer ERP is gated behind a feature flag.
  • Shared data tables: writes to bronze Iceberg tables are append/merge-only (resolve_iceberg_write_disposition); replace is prohibited (it would wipe other tenants).

Solo-developer self-review checklist (the author confirms before merging, when no independent reviewer is available): the diff does only what the PR describes; CI is green and tests cover the change; no secrets or credentials are added; any ERP-write / auth / migration change is flagged and double-checked; the changeset states the user-facing impact.

4. Emergency / hotfix changes

Section titled “4. Emergency / hotfix changes”

Production hotfixes follow the documented break-glass path (docs/branching.md): a hotfix-labeled PR may target main directly; it still requires review and is reconciled back into staging afterward so history does not diverge.

5. Separation of duties

Section titled “5. Separation of duties”

Authoring and releasing are separated. A change is written and merged to staging, but reaching production requires a separate, manual promotion (§2) — a deliberate second checkpoint distinct from writing the code. With a second engineer, independent review adds approver-vs-author separation; operating solo, separation is provided by the non-bypassable automated gates plus the distinct promotion step — the author cannot both write code and silently ship it to production without passing those gates and taking that deliberate release action.

6. Review

Section titled “6. Review”

Reviewed at least annually by the Security Owner.