NFR-COMPAT-2 asks for the v1 channels to be stated, and says why in its own
second sentence: the channel decision and the storage design are coupled. There
was nowhere that statement lived. packaging/ held a PKGBUILD and a desktop
entry, which is a recipe rather than a decision, and the coupling the
requirement points at was therefore invisible.
docs/distribution.md states five channels and, more usefully, which two of them
exist only as promises. It also records what every channel has to get right
independently of format — the one identifier that appears in four places, the
metainfo, Vulkan being a requirement rather than a preference while NFR-R8 is
open, a secrets daemon being optional rather than required, and the LFS pointer
check that stops a package shipping 130 bytes where an 11 MB model should be.
§4 is the part worth reading. Preparing a Flatpak is what surfaced that
FR-PLAT-LIN-3 is not satisfied and cannot be satisfied by packaging alone: a
folder library is chosen by typing an absolute path into an EndpointOnly field
that checks it with std::fs, and nothing in the tree calls the FileChooser
portal. Inside a sandbox that path does not exist, so the launch screen refuses
it. Import fails one step earlier, because a sandboxed process reads its own
mount namespace and a card mounted on the host is not in it.
That is written down rather than fixed with --filesystem=host, and the argument
for not fixing it that way is §2: the Arch package and an AppImage both hand the
application the same unrestricted process the developer runs it in, so Flatpak
is the only Linux channel that tests whether a design assumed unrestricted
access. Granting the permission removes the only reason to ship it.
The reverse coupling on Android is recorded too. NFR-COMPAT-2 says Play
distribution is what makes ARCH §6.9 binding; §6.9 is verified rather than
assumed, so SAF is already unconditional and a sideloaded build would gain
nothing by asking for more. Play is deferred over the GPLv3 question, which is
a licence-reading exercise and blocks nothing in the storage design.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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>
dtourolleandClaude Opus 5