Contributing to Atomic

September 12, 2026 · View on GitHub

Thanks for your interest in contributing to Atomic. This guide explains how to prepare a local checkout, make changes, and submit them for review.

Getting started

  1. Fork and clone the repository.

  2. Install dependencies with npm:

    npm ci --ignore-scripts

    The committed .npmrc applies a three-day minimum release age to anything you add with npm install, and pins exact versions.

  3. Read DEV_SETUP.md for the full development setup, local CLI workflow, testing notes, and repository layout.

Development guidelines

  • Use npm for installs, builds, checks, and tests. Bun compiles the release binaries and runs scripts/*.ts. Do not use yarn or pnpm, and do not run bun install — see the Tech Stack table in AGENTS.md for the full split.
  • Keep changes focused and small enough to review.
  • Follow the existing TypeScript style and package conventions.
  • Add or update tests when changing behavior.
  • Do not add build output, generated artifacts, or unrelated formatting changes.

Claiming an issue

For every external contribution, first open a proposal issue for a new idea or discuss an existing issue with your intended approach. Wait for explicit maintainer approval of the proposed scope before implementing it and opening a pull request. This applies to all changes, including small fixes and documentation-only changes, and to draft pull requests.

Opening an issue, expressing interest, silence, or assignment alone does not constitute scope approval. A maintainer will respond as soon as possible. An expression of interest alone does not reserve an issue.

Assignments are normally held for seven days. Post a progress update if you need more time. Maintainers may release an assignment when there has been no activity.

Avoid competing pull requests for assigned issues. Coordinate with the assignee and a maintainer first; uncoordinated duplicate pull requests may be closed.

Assignment reserves the opportunity to work on an issue but does not guarantee merge. Maintainers are exempt from this issue-first approval process and may work on issues and open pull requests without being assigned.

Testing and checks

Before opening a pull request, run the most relevant checks for your change:

npm run check
npm run test:unit

For broader changes, use:

npm run test:all

Per-test timeouts

Every suite runs with a shared 30000 ms per-test budget, declared once as TEST_TIMEOUT_MS in the root vitest.config.ts and applied to all three projects. That single value is the whole policy:

  • Do not restate the budget in a package script, in bunfig.toml (Bun ignores [test] timeout), or only in the CI workflow (CI and local runs would drift apart), and do not make it platform-specific.
  • Pass an explicit third-argument timeout only when a test is structurally heavy — it reloads the full builtin package graph, spawns a real CLI child, runs tsc, or installs a built package. Otherwise rely on the shared default; never restate it.
  • CI scores every test against its effective timeout on every attempt, including a failed one that a bounded retry later rescued, and fails the step at 70 % of budget. The full duration table is uploaded as a .ci-diagnostics/ artifact. If your test trips that gate, make it faster rather than raising the shared default.
  • That scoring reads vitest's JSON reporter, which the CI wrapper requests alongside the human one so the step log stays readable. A run that executes tests without producing durations fails the step instead of reporting no slow tests.

Tests run in parallel

vitest runs test files concurrently and this repository sets no pool or worker limits, matching upstream pi. A test that only passes on an idle machine is a bug in that test: give the real work headroom and derive the assertion from a named constant. Do not skip it, serialize the suite, or shard.

Pull requests

External contributors must complete the issue discussion and explicit scope approval process above before opening any PR. PRs opened without prior approval may be closed pending discussion.

When opening a PR:

  • Describe the problem and the solution clearly.
  • External contributors must link the approved issue with Closes #<issue-number> or Related: #<issue-number>.
  • Include test output or explain why tests were not run.
  • Call out breaking changes, migration steps, or follow-up work.

Workflows contributions

Looking to contribute workflows? Check out the atomic-workflows repo here.

Questions

For questions, help, feedback, or feature ideas, join the Atomic Discord community.