Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
64 lines (46 loc) · 2.5 KB

CONTRIBUTING.md

File metadata and controls

64 lines (46 loc) · 2.5 KB
Raw

Contributing

Thanks for helping improve protoarray. This page covers the rules that are easy to break by accident; CLAUDE.md describes how the codebase fits together.

Getting set up

pnpm install
pnpm test

There is no build step. What you edit in src/ is what ships.

The rules that are not negotiable

1. No runtime dependencies. package.json has no dependencies key, and it stays that way. When a small helper is needed, copy it into src/ with an attribution comment. devDependencies are fine.

2. Plain CommonJS. require/module.exports, no import/export, no TypeScript syntax, no 'use strict'. Built-in modules use the node: prefix, and relative requires include .js.

3. No Node builtins in src/. Everything under src/ runs in browsers too. tests/unit/platform.test.js fails if a builtin is required there. If a platform-specific module is ever needed, it goes in a runtime twin mapped through the package.json browser field.

4. A public API change touches three files together: src/index.js, index.d.ts and a test (plus a tests/types assertion for anything new). tests/unit/export-parity.test.js fails when the runtime exports and the declarations drift apart.

Tests

Node's built-in node:test, no external framework.

  • tests/unit/*.test.js: one file per area. Run one with node --test tests/unit/codec.test.js.
  • tests/types/*.test-d.ts: tsd assertions against index.d.ts.

pnpm run test:coverage enforces 100% lines, statements, branches and functions in every file under src/ and bin/ (the CLI is covered through the processes cli.test.js starts).

New behavior needs a test that fails without the change. For a bug fix, the test should describe the bug, not the implementation.

Before opening a PR

pnpm run lint
pnpm run format
pnpm run test:coverage
pnpm run test:types
pnpm run check:dts
pnpm size --max-gzip 23

prepublishOnly runs lint, format check, coverage, tsd and check:dts; CI adds the bundle-size gate (23 KB min+gzip for either entry) and the docs build. Treat that as the merge gate. Coverage of src/ and bin/ is 100% with no c8 ignore comments: an unreachable branch is removed, not ignored. Measure with pnpm size after any change to src/; when a change needs more than the gate, raise it to the next whole KB above the measured size in the same commit.

Commit messages follow Conventional Commits (feat(scope):, fix(scope):, test:, docs:).