Searchable Feature gallery

Project governance

This page defines how maintainers make decisions, preserve compatibility, verify changes, and manage performance and releases.

Decisions and contributions

Architecture changes require an ADR with status, context, decision, alternatives, and consequences. Small implementation choices belong in code and tests. Contributions should solve a concrete consumer problem, keep the public API small, preserve deterministic output, and avoid runtime dependencies unless their cost is explicitly opt-in.

The accepted ADR index is Architecture decisions. Draft designs do not become commitments merely because they are archived.

Compatibility

When published, the four public npm packages follow semver and move in lockstep. The manifest format uses its own integer version and compatibility table; see Compatibility. Breaking API or format changes require migration documentation and focused compatibility tests.

Testing

Behavior changes require unit or integration coverage at the narrowest useful level, plus cross-package or browser coverage when they cross a boundary. Index-format changes require schema validation, TypeScript/Python conformance, malformed-input tests, and JSON/binary parity where applicable. Ranking changes require snapshot review against the configuration testbed.

CI gates include build, Vitest, Python tests, TypeScript type checking, Biome, browser tests, bundle size, and package consumer fixtures. Documentation examples must use exported symbols and current option names.

Performance policy

Measure before changing storage or loading architecture. Benchmarks must state corpus, query set, browser/runtime, cold or warm state, output size, timing method, and repeat count. Keep correctness coupled to performance work: an optimization is not accepted if it changes results without an explicit product decision.

The core client, worker, and Service Worker share a 15 KB gzip budget enforced by pnpm size. Large optional dependencies must stay lazy and external to that core budget.

Release checklist

Repository visibility and its post-public security settings are tracked in the Public launch checklist. Package publication is a separate release operation.