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.

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.

License

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

Thank you for considering a contribution.