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/soulcraft/brainy. It's anonymously readable and cloneable — no account needed to browse, clone, or build.

github.com/soulcraftlabs/brainy is a public read-only mirror. It's a fine place to read code or star the project, but issues and pull requests opened there won't be picked up — please use one of the paths below instead.

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/soulcraft/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.

2.7 KiB Raw Blame History