Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
237 lines (195 loc) · 12.2 KB

CONTRIBUTING.md

File metadata and controls

237 lines (195 loc) · 12.2 KB
Raw

Contributing to testsprite-cli

Thanks for contributing! Docs fixes can go straight to a pull request. For code changes — even small ones — please follow the issue-and-claim flow below, so we can agree on the approach before you invest time.

Questions & support

This project is young — if anything is confusing or broken, please tell us:

Please keep bug reports and feature requests in Issues and questions in Discussions, so the issue tracker stays a clean, actionable list.

Contribution model

  • Docs PRs whose title starts with docs can be opened without an issue (linking one is still appreciated).
  • Code changes, including small fixes, new commands or flags, changed output, new dependencies, and refactors, follow issue-first:
    1. Find an existing issue, or open a new one describing the change. Community contributors can have at most 3 open issues of their own at a time. This counts issues you opened that are still open, unless someone else has claimed them; your PRs and other people's issues don't count. An issue stops counting once it is closed (its PR merged with Closes #123, closed by a maintainer, or closed by you) or claimed by someone else. A fourth is closed by the bot with a list of the three; you can't reopen it, so open it again as a new issue once you're under the cap.
    2. If the issue is new, wait for triage — we check proposals against VISION.md and the standing policies below before any code is written, so you don't invest in something we'd ask you to rework or decline.
    3. Once it has an accepted, good first issue, or help wanted label, claim it by commenting /assign at the start of a line (a Markdown list marker and text after the command are fine). The bot also recognizes phrases such as "I'd like to work on this", "can I take this?", and "I'll take this". It ignores quoted text and code. You can release a claim with /unassign. Community contributors can hold at most 3 open claimed issues; the bot refuses further claims until a slot is free. It replies with your open assignment count. If you opened the issue, it is reserved for you for 48 hours after it is accepted: only you can claim it in that window, and to keep it you need a linked PR (a draft is fine) within those same 48 hours. After that anyone can claim it. An issue someone has already claimed can't be claimed by anyone else until it is released.
    4. Open your PR with a same-repository issue reference in its description: Closes #123, Fixes #123, or Resolves #123. For an umbrella issue that should stay open, use Part of #123, Refs #123, or Related to #123. The bot also accepts Close/Closed, Fix/Fixed, Resolve/Resolved, and Ref/Reference/References (case-insensitive, with an optional colon before #123).
  • Claim lifetime: the bot warns after 24 hours and releases a claim after 48 hours unless you have an open PR whose description references the issue as in step 4 (a bare #123 mention does not count). Draft PRs count, so opening a draft early holds the claim while you work. You can /assign again if the issue is still free.
  • PR gate: a bot checks every community PR whose title does not start with docs for a referenced issue assigned to the PR author. PRs that don't meet this get the needs-issue label and a failing gate check, and are not reviewed until it's fixed. If you claimed after opening the PR, edit the PR description to re-run the check.
  • Suspected security vulnerabilities are the exception to "file an issue": report them privately per SECURITY.md instead.
  • We do accept community code contributions — this is an actively maintained open-source CLI, not a read-only distribution mirror.
  • See VISION.md for what is in and out of scope.

Standing scope policies

Pre-decided policies, so proposals don't have to relitigate them:

  • Runtime dependencies are budgeted. The CLI ships with a deliberately tiny runtime dependency set (commander, valibot, plus undici — approved for HTTPS_PROXY/HTTP_PROXY/NO_PROXY support). Any new runtime dependency needs explicit maintainer sign-off in the issue, before the PR. Utility modules land only together with the consumer that uses them — standalone libraries are declined.
  • agent install targets. Shipped: claude, antigravity, cursor, cline, codex, kiro, windsurf, copilot. Accepted and in progress: gemini. A proposal for a new target needs (1) the editor's official rules/skill file mechanism, documented, and (2) the proposer prepared to maintain the target going forward.
  • Outbound network calls. The CLI talks only to the configured TestSprite API endpoint. The one approved exception is an opt-out-able npm registry version check (at most once per 24h, carrying nothing but the package name, fully silenced by its env opt-out and in CI/JSON/dry-run modes or when stderr is not a TTY). Any other outbound call is out of scope.

We aim to give every issue and PR a first response within 5 business days (best-effort). If something has gone quiet longer than that, a polite nudge on the thread or in Discord is welcome.

Prerequisites

  • Node 20.19+, Node 22.13+, or Node 24+ (development happens on Node 22).

Build from source

npm install
npm run build          # tsc → dist/
npm link               # optional: makes `testsprite` resolve to your local checkout

The compiled binary lands at dist/index.js. During development you can run it directly with node dist/index.js <command>.

Testing

npm test               # Vitest unit suite (mock-based; no network or credentials)
npm run test:coverage  # Vitest with v8 coverage (>= 80% gate)
npm run test:e2e       # Local end-to-end suite (builds first; no credentials needed)

Unit and local-e2e tests are mock-based and run with no external dependencies — this is the full suite contributors run locally and in CI. New behavior should come with tests; keep mocks deterministic (no real timers or network).

Lint, format, and type-check

npm run lint           # ESLint
npm run lint:fix       # ESLint with --fix
npm run format         # Prettier (write)
npm run format:check   # Prettier (check only)
npm run typecheck      # tsc --noEmit

Developing on Windows

Native Windows (no WSL, no Git Bash required) is a fully supported dev environment — you only need git and Node ≥ 20. npm ci, npm run build, npm test, npm run lint, and npm run typecheck all run the same way as on macOS/Linux, and CI runs the unit suite on windows-latest as the reference environment (see CI checks below) — if it's green there, it's green on your machine.

A couple of things worth knowing:

  • Line endings are normalized to LF on checkout via .gitattributes (core.autocrlf doesn't need any special local configuration).
  • --out/bundle-path flags accept native Windows paths (C:\Users\...) including a trailing backslash and a bare drive root (C:\).
  • A small number of tests that create real filesystem symlinks are skipped on Windows (creating a symlink there needs Administrator rights or Developer Mode, which isn't guaranteed on hosted CI) — the safety behavior they cover is still exercised on the Linux/macOS CI jobs.

Hit something that doesn't work on Windows? Please file it — see Questions & support above, and feel free to tag it good first issue if it looks like an isolated fix; we'd rather know than have you route around it silently.

CI checks

These run on every PR and are required by review policy — a maintainer will not merge a PR with a red check — but nothing at the platform level blocks the merge button on this repo, so treat them as "must be green before review," not as an automatic gate:

  • ESLint + Prettier clean
  • TypeScript type-check clean
  • All unit tests passing on Linux (Node 20 + 22) and on Windows (windows-latest, Node 22)
  • Coverage ≥ 80% on lines / statements / functions / branches
  • Build + smoke test of the CLI binary

Fork pull requests run CI with a read-only token and no secrets by design.

First PR here? CI needs a maintainer click first

GitHub requires a maintainer to approve a first-time contributor's workflow run before it starts. If this is your first PR in this repo, your checks tab will show only a couple of lightweight items (a gate check and CodeRabbit) — the checks listed above will be absent, not failing. That's expected and says nothing about your code: it means the run is queued waiting for someone to click "Approve and run workflows," not that anything broke.

We don't get an automated signal when a run is stuck in that state, so if it's been a while (see the response-time note above), ping us on Discord or leave a comment on the PR and we'll approve the run.

How we review

Every PR gets an automated first-pass review from CodeRabbit (it posts a summary and inline suggestions), followed by a human review covering correctness, tests, style, scope, and a supply-chain/security check. A code owner approval is required before merge. The automated review is a helper, not a gate — a maintainer always makes the final call.

Branches, pull requests, and releases

  • main is the only long-lived branch in this repo — it tracks the latest released code.
  • To contribute: fork the repo, create a branch in your fork, and open a pull request against main. You don't need any access to this repo to do that.
  • Branch names use a type prefix: feat/…, fix/…, docs/…, refactor/…, test/…, chore/….
  • Commit messages follow Conventional Commits — e.g. feat(cli): …, fix(http): ….
  • Code, tests, and workflow/script files should explain themselves in plain language rather than reference an internal tracker ticket number; put that in the PR description or commit message instead (a CI check enforces this).
  • Keep PRs focused — one logical change per PR is easier to review and merge.
  • This repo is the open-source distribution of the TestSprite CLI; the canonical development happens internally and is mirrored here. After your PR is merged, maintainers fold the change into the internal source of truth and it ships in the next release sync — so a file you touched may later be updated by a sync commit. Your authorship is preserved in the merge.
  • Releases are cut by pushing a semver git tag (vX.Y.Z), which publishes the package to npm (via OIDC trusted publishing) and creates a GitHub Release.

Project layout

  • src/commands/ — one module per command group (auth, project, test, agent).
  • src/lib/ — shared building blocks: http (client + retry/backoff), poll (run polling), output (JSON/text rendering), config / credentials (profile + API-key handling), errors (typed envelopes + exit-code mapping), target-url (URL pre-flight guard), and dry-run/ (offline sample responses).
  • src/index.ts — CLI entry point; maps API errors to exit codes.
  • test/ — Vitest unit and snapshot suites; test/mock-backend/ provides the MSW-based fake API used by the unit suite.

See DOCUMENTATION.md for the full command reference.

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0. No separate CLA is required — inbound contributions are simply licensed under the project's existing Apache-2.0 terms.