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.
77 lines
3.3 KiB
Markdown
77 lines
3.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
git clone https://source.soulcraft.com/soulcraftlabs/open-brainy.git
|
|
cd brainy
|
|
npm install
|
|
npm run build
|
|
npm test
|
|
```
|
|
|
|
Tests run on [Vitest](https://vitest.dev/). `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](https://www.conventionalcommits.org/).** `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](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](LICENSE). Contributions are accepted under the same
|
|
license — there's no CLA to sign.
|
|
|
|
Thank you for considering a contribution.
|