Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
85 lines (56 loc) · 2.22 KB

CONTRIBUTING.md

File metadata and controls

85 lines (56 loc) · 2.22 KB

Contributing

Thanks for contributing to @putdotio/sdk.

Setup

Install dependencies with Vite+:

vp install

Then install the stock VitePlus hook wiring for this clone:

vp config

Validation

Run the full repo guardrail before opening or updating a pull request:

vp run verify

That command runs formatting, linting, package build, unit tests, and coverage using the same repo-local entrypoint CI relies on.

The coverage guardrail is unit-only and counts all production files under src/**. Live tests are intentionally separate confidence checks and do not count toward the coverage threshold. The low-risk consumer publication-surface target is the exception and runs in CI on every push and pull request.

Live Verification

Live verification is opt-in and uses the real put.io API.

Start with the example env file:

cp .env.example .env

Run the full live suite:

vp run test:live

Run just the publication-surface target:

vp run test:live:consumer

This is optional for normal contributions and requires real credentials. Use it when you need backend sanity checks, release confidence, or verification for stateful flows that unit tests cannot prove.

Bootstrap runtime tokens with 1Password:

export OP_SERVICE_ACCOUNT_TOKEN="<service-account-token>"
op run --env-file=.env.example -- vp run bootstrap:tokens

For single-target commands, safety rules, and fixture expectations, see Testing.

Development Notes

  • Prefer vp for repo commands.
  • Treat @putdotio/sdk as a new public package, not a compatibility wrapper around putio-js.
  • Keep the public surface domain-first and Effect-first.
  • Put end-user usage in Overview. Put deeper contributor and architecture notes in docs/*.

Useful references:

Pull Requests

  • Keep changes focused and explicit.
  • Add or update tests when behavior changes.
  • Update docs when the public surface, contributor workflow, or verification model changes.
  • Prefer follow-up pull requests over mixing unrelated cleanup into one batch.