Skip to content

contributing.md

Latest commit

 

History

History
85 lines (60 loc) · 2.54 KB

contributing.md

File metadata and controls

85 lines (60 loc) · 2.54 KB
title Contributing — Dev Quickstart

Contributing — Dev Quickstart

Thanks for helping improve STAN! This project follows a services‑first, test‑first philosophy. Here’s how to get started locally.

Setup

Prereqs:

  • Node ≥ 20
  • Git

Clone and install:

git clone https://github.com/karmaniverous/stan-cli.git
cd stan-cli
npm i

Common tasks

Run the full test and validation suite:

npm run lint
npm run typecheck
npm run test
npm run build
npm run docs
npm run knip

Dev fallback (bootstrap scripts)

If stan run is temporarily broken while developing STAN itself, use the bootstrap scripts as a stopgap to exercise the pipeline and generate the usual artifacts (outputs and archive) without relying on the CLI:

  • Primary orchestrator (runs multiple tasks concurrently and then archives):

    npm run bootstrap

    This will:

    • run typecheck, lint, test, build, and docs concurrently,
    • write deterministic outputs to .stan/output/*.txt,
    • and create .stan/output/archive.tar.

  • You can also run individual bootstrap tasks:

    npm run bootstrap:typecheck
npm run bootstrap:lint
npm run bootstrap:test
npm run bootstrap:build
npm run bootstrap:docs
npm run bootstrap:archive

Note: these bootstrap scripts are for STAN development only (fallback tooling). Consumers of STAN should use the CLI directly, e.g. stan run.

Coding standards

  • Single‑Responsibility modules; prefer small, testable units.
  • Plain unified diffs for patches.
  • Keep .stan/system/stan.todo.md updated with each change set and include a commit message (fenced) in chat replies.

Barrels & cycle‑avoidance

  • Prefer importing from barrels (directory index.ts) in tests and higher‑level modules to keep call sites stable and avoid deep paths.
  • Avoid importing a barrel from within its own subtree to prevent cycles. Within a subtree, prefer local relative imports instead of the subtree’s barrel.
  • Keep barrels as the only public entry points for their areas; treat internal files as implementation details.

Submitting changes

  1. Create a feature branch: git checkout -b feature/your-change
  2. Ensure all CI tasks (lint, typecheck, test, build, docs) pass locally.
  3. Open a Pull Request with a clear description and links to any related issues.
  4. Expect a review focusing on tests, documentation updates, and module design. Adherence to the project's design principles is key.

Questions?

Open a GitHub issue with details or propose a design sketch in the PR description.