Contributing to libbui #
Thank you for helping. The repository lives on Tangled, so please open issues and pull requests there.
Read AGENTS.md first for project guidelines. libbui stays a polite client of a service that suspends real people's library cards, and nothing prints over the terminal the interface owns.
Layout #
| Crate | What it owns |
|---|---|
crates/libby |
The async Libby client: account, catalog, library finder. No UI, no disk. |
crates/libbui-core |
Configuration, paths, the stored pairing, the download engine, sidecars. No UI. |
crates/libbui |
The interface (app/, screens/, ui/) and the command line (cli/). |
The interface is Elm-style: input becomes an Action, App::dispatch
updates state and returns tasks, and rendering is a pure function of state.
Screens never do I/O themselves; they talk to Libby through the Api trait,
which tests replace with a scripted fake.
Before sending a change #
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
Screens are tested through the test harness and insta snapshots. When a
snapshot changes, accept it with INSTA_UPDATE=always cargo test -p libbui
and read the diff: the snapshot is the UI, so if it looks cramped or
misaligned, fix the UI rather than the snapshot. No test may touch the
network or your real configuration.
Trying it without an account #
LIBBUI_SENTRY_URL, LIBBUI_THUNDER_URL and LIBBUI_LOCATE_URL point the
account, catalogue and library-finder services at a stand-in, which is how
crates/libbui/tests/account.rs drives the real binary. Each must be an
http(s) URL ending in /; anything else is refused rather than ignored.
The account token goes wherever LIBBUI_SENTRY_URL says, so only ever
point it at a server you run.
Conventions #
- Every user-visible string goes in
crates/libbui/locales/en-US/*.ftland is looked up witht!. Use Fluent selectors for plurals; never build a sentence by joining pieces. - Never use colour alone: pair it with a symbol or a word, and use theme
roles and
Symbolsso--asciiandNO_COLORkeep working. - No
unwrap()outside tests. Prefer an error the person can act on to a silent default. - Commit messages are conventional and lowercase, such as
feat(search): add a language filterorfix(core): keep partial files.
Releasing #
- Set
version = "X.Y.Z"in the rootCargo.tomland rename## [Unreleased]inCHANGELOG.mdto## [X.Y.Z]. That section becomes the release notes. - Commit, then tag and push:
git tag vX.Y.Z && git push origin vX.Y.Z. - The tag's
releaseworkflow builds and smoke-tests the static Linux binaries.
A tag with a hyphen, such as v0.2.0-rc.1, marks a prerelease.
Translations #
Copy crates/libbui/locales/en-US to a folder named for your language (for
example locales/de-DE) and translate the values, keeping every key. Try it
with libbui --lang de-DE.