Skip to content

Contributing

What it is

How to add to ManpowerIQ without breaking the things this guide documents. The substance lives in the Conventions section; this page is the entry point and the contribution flow.

Before you build

  • Read the relevant convention first. Adding a lookup CRUD? → Lookup CRUD template. Returning a domain error? → Exceptions. Reusing/extracting a helper? → Helpers catalog + §G discipline. Adding a localized message? → BE i18n keys.
  • Mirror an existing entity rather than inventing a shape — the conventions are "copy the last one that fits", not a framework.
  • Check the build status honestly — if you're touching something marked PARTIAL/PLANNED, keep the status accurate.

The flow

  1. Work in a phase. Substantial changes follow the audit-first discipline: build a phase, audit it (build green, decisions logged, regressions checked, "do-not-assume" list), then advance. Don't skip the gate.
  2. Migrations — add an EF migration for any schema change; remember reset is drop + recreate, and seed INSERTs must tolerate it (PB-025). Apply with dotnet ef database update — there is no migrate-on-startup.
  3. i18n — add resx keys (en + ar in lockstep) and FE en.json/ar.json in parity.
  4. Tests — follow the test patterns: FK-block try/finally ownership, AR-locale content-swap sentinels, and a [Collection("PostgresIntegration")] test for any aggregation (InMemory ≠ Npgsql).
  5. Run the build green — dotnet build, the test sweeps, and (for docs) mkdocs build.

Commit & branch note

The project doesn't enforce a heavyweight commit convention; the lightweight norms observed in history:

  • Branch per feature/ticket, named for the work (e.g. the MIQ-NNN or PB-NNN it implements).
  • Commit messages describe the what + why concisely; co-authorship is recorded with a Co-Authored-By: trailer where applicable.

(This is a light note by design — there was no formally documented commit/branch standard to reproduce; treat it as observed practice, not a mandate.)

Gotchas / constraints

  • Don't extend a locked shared shape to fit a new case — keep it inline (§G discipline).
  • Don't mutate system rows or assume an unaudited write is audited (audit is selective).
  • Don't claim aspirational capability in code comments or docs — keep status honest (the rule this whole guide follows).
  • Pre-production: action the diagnostics cleanup (F9 / PB-114) before any real deployment.