Skip to content

CONTRIBUTION_GOLDEN_PATH.md

Latest commit

 

History

History
293 lines (229 loc) · 14.5 KB

CONTRIBUTION_GOLDEN_PATH.md

File metadata and controls

293 lines (229 loc) · 14.5 KB
Raw
title Contribution Golden Path

Contribution Golden Path

Use this guide to choose the smallest reliable development loop for a pull request. It does not replace the area-specific architecture and security documents linked below; it connects each common change type to its contracts, focused checks, and CI coverage.

The path every change follows

  1. Choose the base before editing. Find the highest active release/v* branch and branch from its tip. Target that branch, not main. If a release freeze is active, do not target the frozen branch; use the next active cycle described in Branching & Release Model.
  2. Name the contracts. Identify every catalog, schema, generated artifact, public API, or user interface that the change affects. The table below gives the minimum starting set.
  3. Write or update focused tests. Production changes in src/, open-sse/, electron/, or bin/ require an automated test in the same PR. Run the smallest test files that prove the behavior, then the listed focused gates.
  4. Let CI run the broad matrix. The complete unit shards, Vitest, coverage ratchet, and production build run on the PR. Run a broad suite locally only when a focused failure points to wider impact or when the change spans several subsystems.
  5. Reconcile before review. Fetch the active base, inspect its new commits and your diff against it, then rebase or merge the base according to the contributor workflow. Resolve generated-file and catalog conflicts from their source, regenerate them, rerun the focused loop, and confirm the PR still targets the active release branch.
  6. Record evidence. In the PR template, list the commands run, every test file added or changed, migrations or feature flags, and any CI-only validation still pending.

Golden paths by change type

Commands below are minimum focused checks, not permission to skip a test that directly covers the behavior you changed.

Provider

Contracts

  • Provider definition in src/shared/constants/providers/ and its composition in src/shared/constants/providers.ts.
  • Models and capabilities in open-sse/config/providerRegistry.ts or its extracted registry files.
  • Executor/translator selection, OAuth or API-key configuration, dashboard assets, and generated provider reference when applicable.
  • Public credentials must use resolvePublicCred(); error responses must use the shared sanitized error helpers. See docs/security/PUBLIC_CREDS.md (git; not compiled into /docs) and Error Sanitization.

Focused loop

npm run check:provider-consistency
npm run check:provider-assets
node --import tsx/esm --test tests/unit/provider-translate-path-golden.test.ts
node --import tsx/esm --test tests/unit/<provider-or-executor>.test.ts
npm run gen:provider-reference   # when the catalog changes; commit the generated diff
npm run lint

Also test every affected request family: chat, Responses, images, embeddings, audio, or video. Review generated catalog and golden diffs as contract changes; do not accept them blindly.

Routing

Contracts

  • Public strategy values and UI metadata in src/shared/constants/routingStrategies.ts.
  • Dispatch and ordering under open-sse/services/combo.ts and open-sse/services/combo/.
  • Combo schemas, persistence, resilience state, model capabilities, and API/UI controls.
  • Auto-Combo Engine and resilience documentation when behavior changes.

Focused loop

node --import tsx/esm --test tests/unit/combo-<behavior>.test.ts
npm run test:combo:matrix        # strategy or dispatch changes
npm run check:known-symbols      # strategy registration changes
npm run lint

Use deterministic mocked-upstream tests locally. Live combo smokes require credentials and are manual, not CI substitutes.

UI / UX

Contracts

  • Next.js route/page and shared component boundaries under src/app/ and src/shared/components/.
  • API response shapes, loading/empty/error states, keyboard and screen-reader behavior, responsive layout, theming, and locale expansion.
  • English UI source strings in src/i18n/messages/en.json; do not hard-code new user-facing copy.

Focused loop

node --import tsx --test tests/unit/dashboard/<feature>.test.ts
npx vitest run --config vitest.config.ts tests/unit/ui/<component>.test.tsx
npm run check:dashboard-typecheck
npm run lint

Run the app for interaction or visual changes and check both narrow and wide viewports. CI runs the production build and broader suites; visual behavior still needs a focused component, Playwright, or documented manual check appropriate to the change.

i18n

Contracts

  • src/i18n/messages/en.json is the UI source; config/i18n.json is the locale source.
  • CLI catalogs live separately under bin/cli/locales/.
  • Preserve ICU placeholders and tags exactly. Do not translate product/provider/model names, protocol and header names, commands, code/JSON identifiers, URLs, environment variables, or protected terms such as OmniRoute, OAuth, MCP, and A2A. The current source list is scripts/i18n/glossary/protected-terms.json.

Focused loop

npm run i18n:sync-ui:dry
npm run i18n:check-ui-coverage
npm run i18n:check-value-drift
npm run i18n:check-glossary
npm run check:cli-i18n          # when CLI strings/catalogs change
npm run lint

This is guidance for the existing system, not an invitation to expand its tooling or key model. Keep i18n patches surgical while the replacement system is being designed. Do not run translation commands that call external services unless the task explicitly requires generated translations and you have reviewed the resulting diff.

CLI

Contracts

  • Public commands and flags in bin/cli/, generated API commands, exit codes, stdout/stderr and JSON output shapes, config/environment behavior, and packaged files.
  • CLI user-facing strings must use the CLI i18n layer and keep en/pt-BR catalogs aligned.
  • Preserve Node as the supported runtime and the published binary contract.

Focused loop

node --import tsx/esm --test tests/unit/cli/<command>.test.ts
npm run check:cli-i18n
npm run build:cli             # generated/bundled CLI changes
npm run check:pack-policy     # package-surface changes
npm run lint

Use the exact command in a temporary data directory when behavior depends on parsing, files, or exit status. CI performs the broader package artifact and ecosystem checks.

Database

Contracts

  • Domain modules under src/lib/db/; import specific modules directly (the old localDb.ts re-export layer was removed).
  • Numbered, idempotent SQL migrations under src/lib/db/migrations/, transaction safety, upgrade behavior, indexes, and every caller affected by the schema.
  • Routes and handlers never issue raw SQL directly.

Focused loop

npm run check:migration-numbering
npm run check:db-rules
node --import tsx/esm --test tests/unit/db/<domain>.test.ts
node --import tsx/esm --test tests/unit/db/migration-<number>.test.ts
npm run lint

Test both a fresh database and upgrade from the prior schema when adding a migration. Database tests must close handles and call resetDbInstance() during cleanup. Run npm run test:bun:db only when the best-effort Bun adapter path changes; Node remains authoritative.

Build / deploy

Contracts

  • Root and workspace manifests/lockfile, scripts/build/, Next.js standalone assembly, dist/ package contents, Electron platform metadata, CI workflows, and deployment sentinels.
  • Supported Node ranges and the allow-listed Bun use in CLAUDE.md must remain intact.
  • Build artifacts stay untracked; dependency, license, workflow, and package policies apply.

Focused loop

node --import tsx/esm --test tests/unit/build/<behavior>.test.ts
npm run check:build-scope
npm run check:lockfile         # dependency or lockfile changes
npm run check:pack-policy      # published package surface changes
npm run lint

Use npm run build locally only when the change affects compilation, standalone assembly, assets, or runtime bundling. Use npm run build:release only for release/deploy validation. CI's build is the final cross-platform signal; platform-specific Electron changes need the matching focused build or smoke evidence.

Developer scripts for a shared machine

Two scripts/dev/ helpers encode the local loop on a devbox where other sessions are active:

scripts/dev/typecheck-touched.sh --base release/vX.Y.Z   # files from merge-base(HEAD, base)..HEAD
scripts/dev/typecheck-touched.sh src/a.ts tests/unit/b.test.ts   # exactly these files
scripts/dev/new-worktree.sh fix/1234-slug release/vX.Y.Z  # isolated worktree, safe in parallel
  • typecheck-touched.sh typechecks only the touched .ts/.tsx files through a temporary tsconfig.touched.tmp.json (extends ./tsconfig.json, types: ["node"], noEmit, incremental: false) under a 6 GB heap, so it replaces the project-wide tsc -p tsconfig.json that OOMs a loaded machine. It prints the errors in touched files plus one summary line and exits 1 for errors in touched files, 2 when the only errors are in imported files or tsc died without diagnostics (read the log it names under _artifacts/typecheck-touched/), 0 when clean. The temp tsconfig is always removed; never commit one.
  • new-worktree.sh serialises concurrent runs on <git-common-dir>/omniroute-new-worktree.lock (waits up to 600 s by default, with a visible message; the script header documents the override) and rolls back the branch it created when git worktree add fails before the worktree exists, so a retry needs no manual git branch -D. The hard-linked node_modules and .husky/_ copy are unchanged.

Local candidate loop

Source tests cannot prove that the packaged artifact boots: packaging lists, pruned dependencies, and native binaries only fail once the tarball is installed and started. npm run dev:candidate (scripts/dev/candidate.mjs) is the local side of the build-once / validate / promote flow from RFC #8084: it builds one candidate, validates that exact artifact, promotes it with directory renames, and rolls it back when the promoted slot fails its health check.

npm run dev:candidate -- run --dry-run --json  # print the plan, change nothing
npm run dev:candidate -- run                   # build + validate + promote, auto-rollback
npm run dev:candidate -- build                 # npm pack + install into _artifacts/candidate/<id>/
npm run dev:candidate -- validate --id <id>    # boot on a free port, /api/health + /v1/models
npm run dev:candidate -- promote --id <id>     # <id> → current, current → previous
npm run dev:candidate -- rollback              # swap current and previous
npm run dev:candidate -- run --from-tarball <file.tgz>  # reuse a tarball built elsewhere (CI)
  • Build once. build packs the current tree (it needs dist/server.js, so run npm run build:release first) or copies --from-tarball, then installs the tarball into an isolated npm prefix, because the tarball carries no node_modules. The id is the short HEAD sha (-dirty when the tree has local changes) or tgz-<sha256> for a tarball. A clean id that is already built is reused instead of rebuilt; pass --force to rebuild it.
  • Validate the package, not the source. validate starts the installed CLI (serve --port <free port>) with a fresh DATA_DIR=<candidate>/data, fake secrets, and the operator's OMNIROUTE_API_KEY, STORAGE_ENCRYPTION_KEY and INITIAL_PASSWORD removed from the environment, so it checks the keyless loopback posture of a fresh install. It waits for GET /api/health to return 200, requires GET /v1/models to return 200, stops the process group, and records the verdict in validation.json together with the tarball hash.
  • Promote the same artifact. promote refuses a candidate without a passing validation for its current tarball hash. The default active slot is _artifacts/candidate/current; --target <dir> selects another directory on the same filesystem, and its previous slot is <dir>.previous. Each rename is atomic, and a failure partway through reverses the renames that already ran.
  • Roll back. run validates the promoted slot again and swaps current and previous back when that check fails. A candidate that fails the first validation is never promoted.

Everything is written under the gitignored _artifacts/candidate/; an existing OmniRoute installation and its data directory are never touched. The promoted CLI is _artifacts/candidate/current/prefix/bin/omniroute; start it with your own DATA_DIR when you use it. Exit codes: 0 success, 1 failed validation or promotion, 2 usage error or missing build.

Local loop versus CI

Run locally for each patch CI supplies the broad signal
Direct behavior tests and category gates above Sharded full unit suite and serial tests
npm run lint Vitest suites and coverage/quality ratchets
Typecheck or build only when the affected contract calls for it Production build, security, docs, dependency, and PR-policy gates
Manual interaction/live checks only when automation cannot prove the behavior Cross-job integration and platform checks configured by workflow

A green focused loop is evidence about the changed contract, not proof that unrelated CI checks will pass. Conversely, do not make every local edit wait for the full repository matrix.

Reconciliation checklist

Before requesting review:

  • Confirm the PR base is still the highest active release/v* branch.
  • Fetch that base and review commits that landed since you branched.
  • Review git diff <active-base>...HEAD for accidental or generated churn.
  • Resolve catalog and generated-document conflicts by updating the source and regenerating output.
  • Rerun every focused test/gate listed in the PR description after reconciliation.
  • Never weaken assertions or drop required tests merely to match a moved base.

For release-freeze and retargeting rules, use Branching & Release Model. For the complete CI inventory, use Quality Gates Reference.