Contributing

Contributing

The project-wide contributor guide is CONTRIBUTING.md in the umbrella repo, with per-repo specifics (build instructions, test commands) in each sibling repo's own CONTRIBUTING.md. Behaviour expectations are in the Code of Conduct. Forge is licensed Apache 2.0.

Where to file it

Open issues and PRs in the repo that owns the affected code — see the repo table on Home. Cross-cutting design discussion belongs on the umbrella repo, where the specs live.

Getting set up

git clone https://github.com/armoryworks/forge.git
cd forge
./bootstrap.sh        # clones the sibling repos alongside this one

bootstrap.ps1 is the PowerShell equivalent. To actually run the stack locally, follow Installation — ./setup.sh --source builds images from your sibling checkouts rather than pulling from GHCR.

Before you push

Forge enforces its standards mechanically, so running the gates locally saves a round trip. See Architecture § Standards are enforced for how the ratchet works.

forge-ui

npm run lint && npm run lint:i18n && npm run test -- --watch=false
npm run lint:standards

Translations live only at public/assets/i18n/{en,es}.json, with enforced 1:1 key parity between locales. A new user-facing string means a key in both files.

forge-api

dotnet test
dotnet test --filter Architecture     # the standards + capability-gate tests

Some integration suites need a real PostgreSQL via Testcontainers, so they require a working Docker daemon.

Things that will get a PR sent back

• Adding an EF Core migration. The schema is owned by forge-db as desired-state SQL — see Architecture. There are no migrations to add.
• Calling DateTime.UtcNow directly. Inject IClock.
• A new controller with no capability attribute. An architecture test enforces gating by reflection; see Capability Gating.
• Hardcoded colours, console.log, or inline templates in new UI files. The lint ratchet allows existing debt to sit but will not accept new debt.
• Improving a ratcheted file without regenerating its baseline. Improvements fail the check until you rerun with the baseline-update environment variable and commit the rewritten baseline in the same commit. Baselines are never hand-edited upward.

Writing docs

Docs are part of the change, not a follow-up. Read Documentation Map for where a new document belongs and what frontmatter it needs — placement is enforced by tooling.