# Contributing to Bearout
Bearout is an early experiment. The most useful changes are small vertical
slices driven by a project under [`samples`](samples/). Grow a sample until
the engine cannot express what it needs, then grow the engine. Read
[`AGENTS.md`](AGENTS.md) and [`docs/design.md`](docs/design.md) first.
## Development setup
The toolchain is pinned with [mise](https://mise.jdx.dev):
```sh
mise run setup
mise run check
```
`mise run check` is the entry point CI uses on Linux: formatting,
whitespace, hook configuration, Clippy, the test suite (which runs every
sample), and the Rust crate generated by the `formula-language` sample.
`mise run fmt` applies the formatters. `mise run samples` regenerates every
sample's outputs after a change to a sample; commit the regenerated files
and each sample's `bearout-state.toml`.
Windows and macOS CI run the test suite and the generated crate through the
same pinned Rust.
`cargo package` warns that the integration tests are not included in the
package; that is intended, since tests and samples stay in the repository.
## Changes to contracts
The bootstrap, the resource envelope, the `x-bearout` vocabulary, the
Starlark ABI, diagnostic codes, and generated outputs are contract surfaces
even while experimental. A change to one of them should include:
- the motivating sample or consumer case;
- tests showing the intended behaviour and failure mode, under
`tests/` with a focused fixture rather than a copy of a whole sample;
- an update to the affected samples, `docs/`, and README;
- a note about migration, or the explicit decision that no compatibility is
retained, in the changelog.
Do not add one sample's domain rules to the Rust kernel. Demonstrate that
more than one sample needs a mechanism before abstracting it.
## Commits and licensing
Commit headers follow Conventional Commits, and contributions carry a
Developer Certificate of Origin 1.1 sign-off (`git commit -s`). Both are
enforced by the `commit-msg` hook that `mise run setup` installs
(`tools/check-commit-message.sh`), for example:
```text
feat(graph): report unresolved resource references
Signed-off-by: Your Name <you@example.org>
```
Unless a file says otherwise, contributions are licensed under Apache-2.0.
Add `SPDX-License-Identifier: Apache-2.0` to source and configuration
formats that support comments. Record substantial AI assistance in the
pull-request description.
## Releases
A release is a tag `vX.Y.Z` that matches the version in `Cargo.toml`. The
Release workflow verifies that match, runs the full check, creates the
GitHub release with generated notes, and attaches binaries for Linux
x86-64, macOS arm64, and Windows x86-64 with SHA-256 checksums. Bump the
version and the changelog in a commit, tag it, and push the tag.
## Pre-publication follow-ups
Before the first release to crates.io:
- add dependency licence and advisory automation (for example `cargo deny`)
with its policy file, and run it in CI;
- register a project homepage before restoring the `homepage` field in
`Cargo.toml`;
- run the Windows and macOS CI jobs on the first pushed commit and fix
anything platform-specific they reveal.