open-brainy/CONTRIBUTING.md

Contributing to Brainy

Brainy is MIT-licensed and genuinely open to outside contributions. This page is the honest, current path — please don't rely on older instructions you may find elsewhere in the repo's history.

Where the project lives

The source of truth is a self-hosted forge: source.soulcraft.com/soulcraftlabs/open-brainy. It's anonymously readable and cloneable — no account needed to browse, clone, or build.

How to contribute

Found a bug, or have an idea? Email brainy@soulcraft.com. No account, no ceremony — you'll get a receipt, and it goes to a human.

Want to send a patch? Two ways, both first-class:

• Email a patch. Run git format-patch against your change and email the output to brainy@soulcraft.com. This is a genuinely supported path, not a fallback — plenty of good contributions arrive this way.
• Open a pull request on the forge. Request an account at source.soulcraft.com (registration is request-with-approval, so allow a little lag), clone, push a branch, and open a PR there. Maintainers review and land it.

Either way, for anything beyond a small fix, opening an issue first (email is fine) to talk through the approach saves everyone rework.

Development setup

git clone https://source.soulcraft.com/soulcraftlabs/open-brainy.git
cd brainy
npm install
npm run build
npm test

Tests run on Vitest. npm test runs the unit suite; see package.json for test:integration, test:coverage, and friends.

Test gate

The release gate is a bare vitest run (no --config flag) — the same command the delta gate and CI's checks invoke. It carries the full correctness suite and nothing else: wall-clock/scale benchmarks (tests/performance/**, tests/critical-performance-benchmark.test.ts, tests/api/performance-benchmarks.test.ts) and the two tests whose outcome depends on the host machine or network rather than the code (tests/package-size-limit.test.ts shells out to the npm CLI; tests/model-loading.test.ts makes a real network call to download a model) are excluded from it, because a timing threshold or a flaky network call has no business failing a correctness check. That whole family runs on demand, in its own exclusive slot, via npm run test:perf.

Standards

• Strict TypeScript. No any escape hatches to dodge the type checker.
• Tests exercise real behavior. No mocking away the thing you're supposed to be testing.
• No stubs, no TODO-code. If something can't be finished, say so and leave it out — don't merge a placeholder.
• JSDoc on every exported function, class, and type.
• Conventional Commits. feat:, fix:, docs:, perf:, refactor:, test:, chore:. Never BREAKING CHANGE in a commit message — major version bumps are a separate, deliberate decision.
• Performance claims are measured or labeled projected. If a PR or its description states a number, cite the benchmark that produced it (see docs/performance-envelopes.md for the pattern). Don't state an estimate as if it were measured.
• Measurements carry numbers, not provenance. Public commit messages and docs give the SHAPE a number was taken at and never where it was taken: no hostnames, no store or deployment identities, no operational anecdotes about someone's running system. "A 14,056-noun / 72,679-verb production-shaped store, measured solo under an exclusive lock" tells a reader everything the number depends on; the machine it ran on and whose data it was tell them nothing except where somebody's infrastructure lives.
• Documents that answer or reference a confidential specification never enter this repository, even summarized. The public docs describe THIS engine and the published contract, and nothing else — a summary of a private document is still that document's contents.

License

Brainy is MIT licensed. Contributions are accepted under the same license — there's no CLA to sign.

Thank you for considering a contribution.