David Snelling
a8c724a202
The manifest's prose pointer named a document that answers a confidential specification, and such a document does not belong in a public repository even in summary. The pointer is dropped — the manifest is generated from this engine's own surface and is self-describing — and the requirement marking it deliberately omits is recorded with the contract's owner rather than here. The standard is written down so this is not relitigated per document.
3.3 KiB
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-patchagainst 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
anyescape 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:. NeverBREAKING CHANGEin 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.