Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
91 lines (65 loc) · 3.03 KB

CONTRIBUTING.md

File metadata and controls

91 lines (65 loc) · 3.03 KB

Contributing

Zero External Dependencies Policy

This project is implemented with Go stdlib-only dependencies. Contributions MUST keep dependency surface zero-external:

  • go.mod MUST NOT include third-party require entries.
  • Go imports MUST be stdlib packages or github.com/niko/bare/....
  • New files should not introduce generated dependency metadata requiring external tools.

Verification before merge

Before submitting changes, enforce the policy by running the zero-dependency check:

  1. Ensure the repository root contains go.mod.

  2. Run:

    .bare/verify.d/03-deps.sh

03-deps.sh is generated by bare init and mirrors the policy in SPECS_v1.md:3.1. The script fails when:

  • go.mod has external module requirements
  • go list -deps reports non-stdlib imports from project packages

Verification script templates

bare init creates three executable files in .bare/verify.d:

  • 01-tests.sh (placeholder for project tests)
  • 02-types.sh (placeholder for type checking or static checks)
  • 03-deps.sh (zero external dependency policy check)

For every script:

  • Exit code 0 means pass, non-zero means failure.
  • The first non-empty, non-comment line ends metadata parsing.
  • # bare:blocking=false as a top-of-script comment disables blocking for that check if verification should continue even when it fails.

Real API example E2E suite

The integration suite in cmd/bare/examples_real_e2e_test.go is optional and opted in only when BARE_REAL_E2E=1 is set. It is not part of the default fast test path.

To run locally:

export BARE_REAL_E2E=1
export ANTHROPIC_API_KEY=...
# or:
# export OPENAI_API_KEY=...
go test ./cmd/bare -run TestIntegrationRealE2EExamples -count=1

Contributors adding new fixtures should follow examples/README.md:

  • Keep fixtures deterministic: each fixture should include all of:
    • TASK.md: title line at the first non-empty line drives bare task add.
    • seed/: minimal repository seed copied into temp run dirs.
    • check.sh: executable validation script run from the fixture repo root.
  • Keep fixture structure as TASK.md, seed/, check.sh.
  • Keep check.sh deterministic and fast (avoid timing checks, remote services, or mutable global state).
  • Prefer acceptance checks that return 0 on success and non-zero on failure.
  • Add optional private validation scripts under BARE_HIDDEN_CHECKS_DIR when evaluation-specific checks are required.

Execution model for new fixtures:

  1. Discover fixture dirs in lexical order.
  2. For each, initialize a temporary repo from seed/, add one task, and run bare run --until-done.
  3. Run fixture check.sh and, if present, optional hidden checks named <fixture>.sh from BARE_HIDDEN_CHECKS_DIR.

For scheduled and non-local execution, use an explicit timeout:

go test ./cmd/bare -run TestIntegrationRealE2EExamples -timeout 45m -count=1

Model API prerequisites remain:

  • ANTHROPIC_API_KEY or OPENAI_API_KEY must be available in the test environment.
  • BARE_HIDDEN_CHECKS_DIR is optional.