A terminal UI for Libby libbui.vinnymac.dev
libbui CONTRIBUTING.md
3.0 kB · 74 lines
Markdown
at main

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/*.ftl and is looked up with t!. 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 Symbols so --ascii and NO_COLOR keep 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 filter or fix(core): keep partial files.

Releasing #

  1. Set version = "X.Y.Z" in the root Cargo.toml and rename ## [Unreleased] in CHANGELOG.md to ## [X.Y.Z]. That section becomes the release notes.
  2. Commit, then tag and push: git tag vX.Y.Z && git push origin vX.Y.Z.
  3. The tag's release workflow 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.