# Contributing to libbui Thank you for helping. The repository lives on [Tangled](https://tangled.sh/@vinnymac.dev/libbui), so please open issues and pull requests there. Read [AGENTS.md](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 ```sh 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`.