Contributing

veR2 protects people's data, so the bar is correctness first: every change comes with tests, and every assumption about R2 comes with evidence. The full guide is CONTRIBUTING.md; this page is the short version.

Before you start

• Bugs and small fixes: open a pull request directly, or an issue if you're unsure.
• Features, new dependencies, API changes: open an issue first so the design can be agreed. Larger work follows a spec → plan → implementation flow in docs/superpowers/.
• Security issues: report them privately as described in SECURITY.md, never in a public issue.

Setup

Requires Node.js 22 or newer.

git clone https://github.com/JBuxo/ver2.git
cd ver2
npm install
npm test
npm run typecheck

The repository is an npm workspace with three packages:

R2 integration tests

Unit tests run against an in-memory store that mirrors R2's verified behavior and need nothing. Integration tests prove that the in-memory store matches real R2, and they need a bucket:

1. Create an R2 bucket used only for testing.
2. Create an API token with Object Read & Write, scoped to that bucket.
3. Copy .env.example to .env.local and fill in the account ID, bucket, access key ID and secret. .env.local is git-ignored.
4. Run npm test. The tests write under ver2-it/<run>/ and delete what they create. Without credentials they're skipped.

Rules that keep data safe

AGENTS.md lists the architecture invariants. They apply to humans too. In short:

• The read path never changes. Live objects stay at their keys.
• Every write is journaled: claim, then storage work, then commit. Never touch the live key before the claim is saved.
• Version objects are immutable. Never overwrite one.
• Never guess. If recovery can't prove an outcome from storage, it reports stuck.
• Validate keys first, before any I/O.
• sdk/src stays runtime-agnostic: no node:* imports, so it can run in Workers.
• New R2 behavior needs evidence: record what you observed in docs/research/r2-behavior.md and add a case to the storage contract suite.

Making a change

1. Branch from main.
2. Write a failing test, make it pass, then refactor. Write paths need tests for a crash before the storage work, a crash after it but before commit, and a direct write racing it.
3. Changed how a storage driver behaves? Add a case to sdk/test/storage/contract.ts.
4. Run npm test and npm run typecheck.
5. Commit with Conventional Commits (feat(sdk): …, fix(cli): …, docs: …), one logical change per commit.

Pull requests

• Keep each pull request focused on one logical change.
• Say whether you ran the R2 integration tests.
• CI must pass. A maintainer runs the integration tests against R2 before merging changes to storage drivers or the engine.

Working on this site

npm run dev -w @ver2/site

To add a docs page, create site/app/docs/<slug>/page.mdx and add it to site/lib/docs-nav.ts. A test fails if a page is missing from the navigation (or the other way round), and if the CLI reference or the errors page falls behind the code.