David Snelling
c8e05189e3
A release audit found hostnames, store identities and operational anecdotes in this branch's commit messages — not trade secrets, but nothing a public repository's permanent history should carry either. The messages were rewritten to keep every number and drop every provenance; the rule is written down here so the next measurement does not have to be caught by an audit.
73 lines
3 KiB
Markdown
73 lines
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.
|
|
|
|
## 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.
|