Give a contributor a way in

There was none. 14 documents, 177 numbered requirements, and all of it
written for someone who has already decided to work on this — nothing that
tells a newcomer which door is unlocked, what a first build needs, or why it
takes so long.

CONTRIBUTING.md points the first door at the operation format, because
"add a develop node" is a genuinely one-file contribution and the best first
experience this codebase can offer: no Rust, no shader edit, no UI change,
and its tests declared in the same file. It teaches the architecture's
central idea on the way through, which is why the invariant test added in
the previous commit is named there rather than left to be discovered.

Three things that were folklore are now written down: Git LFS is a
prerequisite, the first build resolves 826 crates and is not hanging, and
Slint needs pkg-config, libfontconfig1-dev and libxkbcommon-dev. The LFS one
proved itself while writing this — a fresh worktree hit exactly the failure
`dr-segment`'s build script is written to catch, which is the argument for
saying so before it happens rather than after.

rust-toolchain.toml pins 1.92.0 because `build-and-test.yml` already does
and says why: a floating toolchain turns an unrelated push into a mystery
failure. The two checks that gate every push are the two most sensitive to
compiler version — rustfmt's output changes between releases, so a
contributor on a newer stable can produce a diff nobody wrote on a line
nobody touched, and `clippy -D warnings` is the same story with new lints.
`rust-version = "1.92"` in the manifest stays where it is; it is a minimum,
and this is the upper bound it cannot express.

Also states the convention the tooling cannot enforce, from code-health.md
CH-4: close a requirement with a test that would fail if the behaviour were
removed. Coverage that moves slowly and means something beats coverage that
moves quickly.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-08-27 19:33:37 +02:00
co-authored by Claude Opus 5
parent 5e4c7424ed
commit 617262b4da
2 changed files with 186 additions and 0 deletions
+23
View File
@@ -0,0 +1,23 @@
# Pinned so CI, the Android image and a contributor's laptop agree.
#
# `build-and-test.yml` already installs exactly 1.92.0 and says why: a floating
# toolchain turns an unrelated push into a mystery failure. That reasoning
# applies with more force locally than in CI, because the two checks most
# sensitive to the compiler version are the two that gate every push.
#
# `cargo fmt --all -- --check` is the sharp one. rustfmt's output changes
# between releases, so a contributor on a newer stable can reformat a file in a
# way this CI rejects — a diff nobody wrote, on a line nobody touched.
# `clippy -D warnings` is the same story with new lints.
#
# `rust-version = "1.92"` in the workspace manifest is a *minimum* and stays
# where it is; it produces a clear error on an older toolchain rather than a
# confusing one. This file is the other half: an upper bound as well as a lower
# one, so everyone compiles with the same compiler rather than merely a
# sufficient one.
#
# rustup reads this automatically and will fetch the toolchain on first use.
[toolchain]
channel = "1.92.0"
components = ["rustfmt", "clippy"]