Local Development Standard
Purpose
Section titled “Purpose”Local development must approximate CI sufficiently to prevent avoidable “works on my machine” failures.
Nexa context
Section titled “Nexa context”Nexa currently uses multiple package managers and service technologies. Each repository must expose a small, discoverable command surface even if underlying tools differ.
Standard
Section titled “Standard”-
MUST: Document prerequisites and bootstrap commands in README.md.
-
MUST: Provide a deterministic dependency lock file.
-
MUST: Expose standard commands for setup, format, lint, type-check, unit test, coverage, and container build.
-
MUST: Use environment templates with non-secret placeholders.
-
MUST: Keep local test defaults isolated from shared cloud resources.
-
SHOULD: Provide Makefile, npm scripts, Taskfile, or equivalent aliases matching CI stages.
-
SHOULD: Support dev containers where native dependencies are difficult.
-
SHOULD: Allow a developer to run the primary quality suite with one command.
Working model
Section titled “Working model”Recommended command contract: make setup, make check, make test, make coverage, and make image, or equivalent package scripts. CI may call native tools directly, but local aliases should remain stable.
Evidence of compliance
Section titled “Evidence of compliance”Compliance is demonstrated through repository configuration, protected-branch settings, CI results, and review records. Teams should be able to show the evidence without reconstructing it manually.
Common failure modes
Section titled “Common failure modes”Undocumented setup steps, mutable dependency installs, and tests that require personal cloud credentials create onboarding delays and bypassed controls.
Maturity path
Section titled “Maturity path”The initial standard favors consistency and auditable automation. Exceptions and advanced controls are introduced only after the baseline is adopted across repositories.