Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
183 lines (144 loc) · 8.17 KB

CONTRIBUTING.md

File metadata and controls

183 lines (144 loc) · 8.17 KB
Raw

Contributing to launchbound

Thanks for your interest. Issues and small PRs are welcome; large features are better discussed first.

These four projects share one contributor pattern — the same commit rules, the same DCO, the same AI policy, the same CI and release shape: termlens, mossaic, launchbound, reconverge. Learn it once.

1. Dev setup

The default feature set builds and tests without any GPU, CUDA SDK, or Metal — that is a hard project rule, and CI enforces it on plain GitHub runners.

rustup show                # installs the pinned nightly from rust-toolchain.toml
cargo install just         # or: brew install just
just ci                    # fmt, clippy -D warnings, tests, rustdoc, cargo-deny,
                           # schemas, pins, versions, skill

cargo reconverge check also needs no GPU: it runs over Stable MIR as a wrapped cargo build. Everything except an actual benchmark can be developed on a laptop.

2. Project layout

See AGENTS.md.

3. Testing policy

  • The default feature set must pass just ci with no GPU present.
  • Hardware-dependent tests live behind the hardware feature and #[ignore], and never run in CI.
  • Every measured number that reaches a report, a doc or a commit message must come from a re-runnable command, and GPU-measured numbers carry a .gpu-evidence log. Never round in a favourable direction.
  • A model-derived number is labelled estimated everywhere. Reporting an estimate as a measurement is a release-blocking defect.

4. Commit conventions

We use Conventional Commits: feat:, fix:, docs:, test:, ci:, chore:, refactor:, perf: — scope optional (feat(prune): …). Subject line: imperative mood, ≤ 72 characters.

5. Developer Certificate of Origin (DCO)

Every commit must be signed off:

git commit -s

This appends Signed-off-by: Your Name <you@example.com> and certifies you wrote the change or otherwise have the right to submit it under the project license — the Developer Certificate of Origin, the same lightweight model the Linux kernel uses. The sign-off email must match the commit author email; CI enforces this on every commit in a PR.

There is no CLA. DCO only. You keep your copyright.

Forgot to sign off? git commit --amend -s for the last commit, or git rebase --signoff main for a whole branch, then force-push.

One exception, and it is GitHub's rather than ours: a pull request squash-merged through the web UI has its author email rewritten by GitHub after the sign-off was written, so an exact match is impossible by construction. Such a commit must carry a sign-off, but is not matched against an author it did not choose. The commits that went into the PR were already checked, address and all, on the branch.

GitHub also writes that message, and it drops the trailers of the commits it squashed whenever the branch contained a merge commit — pressing Update branch is enough to cause it. The merge then lands on main carrying no sign-off, and main is linear and non-fast-forward, so it cannot be repaired. The check therefore exempts exactly one commit — the tip of a push to main, which can only get there through a pull request that was already checked strictly. Keep your branch up to date by rebasing, not merging:

git fetch origin && git rebase origin/main
git push --force-with-lease

That also matches what main requires: linear history, so a merge commit on your branch is only ever going to be squashed away.

6. AI tooling policy

AI assistance is welcome here — use whatever helps. Every one of these projects was built with it. There is an AGENTS.md briefing coding agents on the layout, the commands, and the house style.

AI attribution is not welcome. No Co-Authored-By trailer naming an assistant, model or vendor; no "Generated with …" footer; no robot emoji; no bot identity as author or committer, save the one carve-out below. Whoever opens the pull request is the author of record, takes responsibility under the DCO, and the history should say so — a tool cannot certify the DCO, which is the whole point of it.

This is enforced, not requested: commit-policy.yml runs check-no-ai-attribution.sh and check-dco.sh over every commit in a pull request. Run them yourself first — both take a range:

.github/scripts/check-dco.sh main..HEAD
.github/scripts/check-no-ai-attribution.sh main..HEAD

If a check fails, rewrite the message rather than arguing with it:

git commit --amend            # the last commit
git rebase -i main            # several, marking each `reword`
git push --force-with-lease

.claude/settings.json turns co-author trailers off for agents that read repository settings. That is a courtesy; the check in CI is the boundary. Contributions authored by an autonomous account are not accepted.

One carve-out: a named dependency bot. Dependabot is exempt from the identity half of the check and from nothing else. The rule exists so that a human is not displaced as the author of record, and a version bump has no human to displace — it is not somebody's work with the credit misassigned. The message rules still apply in full, so a bot cannot carry an AI co-author trailer, a "Generated with" footer or a robot emoji past the check either. Adding another bot means naming it in check-no-ai-attribution.sh: the allowlist is a list on purpose, so that widening it is a visible decision.

7. PR flow

  • Branch from main; name branches feat/…, fix/…, docs/…, ci/….
  • PRs are squash-merged — keep the PR title in Conventional Commit form, since it becomes the commit subject on main. Branches are deleted on merge.
  • Required checks: ci, msrv, check and gate, plus commit-policy (DCO + attribution). All must pass before merge; direct pushes to main are blocked by a ruleset.
  • Every change lands with a test, and the test must be able to fail. If you add a guard, break it once and watch it go red before you commit.
  • Say what you did not do. A PR that lists what it left out and why is worth more than one implying completeness. An honest gap is cheap; a false claim is expensive.
  • Contributing from a fork? Two things are normal. On your first PR the workflows wait for a maintainer to approve them — GitHub's standard first-time-contributor safeguard, nothing you did wrong. And when commit-policy fails on a fork PR it cannot post its explanatory comment (fork PRs get a read-only token); the job log carries the full explanation, including the offending commit and the command that fixes it.
  • Review: expect actionable review within a few days. Small, focused PRs get reviewed faster. Update CHANGELOG.md under [Unreleased] for any user-facing change.

8. Release process

Releases are cut by maintainers only; the checklist lives in docs/RELEASING.md.

9. The pin policy

Three pins move together or not at all: the nightly in rust-toolchain.toml, the cuda-oxide pin, and the reconverge pin. reconverge is a rustc-driver tool — it must be built by the exact rustc it wraps — and cuda-oxide requires the same pin. A bump is its own commit, never mixed with a behaviour change, and re-runs the affected stage gates. The pins.yml workflow reports upstream movement by opening an issue; it never bumps anything. It runs every Monday, and reports a toolchain move as its own line — a channel change means reconverge must be rebuilt, which commit churn does not. Current pins: nightly-2026-08-28, cuda-oxide 26754ae5, reconverge 0.6.0 (installed from crates.io).

10. License

By contributing, you agree that your contributions will be dual-licensed under MIT or Apache-2.0 without additional terms, and you certify the Developer Certificate of Origin via your sign-off.