Skip to content

contributing.md

Latest commit

 

History

History
41 lines (30 loc) · 2.17 KB

contributing.md

File metadata and controls

41 lines (30 loc) · 2.17 KB
Raw

Contributing to SalmonLoop

We welcome contributions to SalmonLoop! As a design-driven project, we prioritize stability, determinism, and clear engineering contracts.

Development Principles

  1. Safety First: Any change that affects the execution loop must maintain or enhance safety guarantees (e.g., no unintended file mutations).
  2. Deterministic Logic: Avoid heuristic "guessing" or AI-driven decision making for core execution logic. Prefer rule-based engineering.
  3. Documentation SSOT: English documentation is the Single Source of Truth (SSOT). Chinese documentation is a user guide and may lag behind.
  4. Test-Driven: New features or bug fixes should be accompanied by unit tests.

Project Structure

  • src/core: The execution kernel. Must remain editor-agnostic and self-contained.
  • src/locales: Internationalization strings. No hardcoded user-facing text in core logic.
  • tests/unit: Bun unit tests. These are mocked to ensure they are fast, deterministic, and don't require a real Git environment or Ripgrep.

Getting Started

  1. Fork the repository.
  2. Install dependencies: bun install.
  3. Run tests: bun run test:full (correctness suite: unit + integration).
  4. Run linting: bun run lint.
  5. Create a feature branch and submit a pull request.

Notes:

  • Use bun for dependency management in this repository.
  • Enable shared hooks once per clone: bun run setup:hooks (this enforces both check:target-runtime-boundary:staged and check:bun-purity:staged before commit).
  • Before opening a PR, run bun run verify to execute Bun purity, target-runtime boundary, lint, typecheck, contract smoke, and correctness tests.
  • When changing performance-sensitive code, also run bun run test:all (or bun run test:perf:all for perf-only validation).
  • When changing A2A transport/network behavior, also run bun run test:integration:network.

Debugging with --verbose

To debug issues, you can use the --verbose flag to get more detailed logs. Use --verbose for basic execution steps, or --verbose=extended for detailed internal states and debug information.

Example:

salmon-loop --verbose=extended --instruction "Fix bug" --verify "bun run test"