David Snelling
415e824a1d
Ruled today: the project's one public home is source.soulcraft.com. The old public repo is archived history and no longer part of any release. - package.json repository/homepage/bugs now point at the forge (this is what the npm page links as Repository/Homepage/Issues) - README CI badge reads the forge pipeline; CONTRIBUTING drops the mirror paragraph (forge account or email patch were already the ruled contribution paths) - release.sh: mirror push + external release step removed; publishes go forge-first (box-held write token, temp userconfig so the token never hits argv; a forge-publish failure aborts before the storefront so the pair can never diverge), then npmjs with the scope-override pin (the fleet npmrc maps @soulcraft to the forge and scope mappings beat --registry); release page created via forge API when a token is present, loud skip otherwise; changelog compare links point home - dead external CI workflow removed (.forgejo/workflows/ci.yml is the live pipeline) Historical CHANGELOG links to the archive stay as written - history is history and the archive serves them read-only.
66 lines
2.5 KiB
Markdown
66 lines
2.5 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/soulcraft/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/soulcraft/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.
|
|
|
|
## 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.
|