Pedro M. de Echanove Pasquin
1fd697aa6d
Documentation pass: every claim in docs/ and the meta files was audited against the source and the drift fixed — around ninety corrections. CONTRIBUTING and the CI workflow now run cargo test with --features test-support (the gated test_support module made both the documented commands and the CI build fail to compile), make example becomes make examples, make doctest-md and the debhelper requirement of make clean are documented, and patch shape asks for a CHANGELOG entry. theming.md loses the nonexistent surface.backdrop, gains the real gradient defaults (linear-rgb, oklab), the six slot variants including typography, the ten-field palette, a truthful effects-consumer table, the ThemePreference/from_hour API and a responsive-sizing note; the stale docstrings in src/theme that fed the drift are fixed too. architecture.md's "Known gaps" section is rewritten against reality (multi-touch slots, xdg-activation, a11y live regions and SetValue/Increment/Decrement are implemented), gains a module map, subsurfaces and window-lifecycle coverage, and correct crustace/loginmanager paths. widgets.md fixes the ten factual errors (stateless spinner, toast/combo via overlays(), tooltip hover contract, row has no max_width, scroll axes, multiline text_edit, dialog panic wording) and now states the column() 16 px default padding — the recurring ambush — plus row's differing 0 default and dialog's max_width. onboarding, README and cookbook get the remaining sweep: build/test instructions, complete example lists, img_widget, clipping-parity honesty, ~30 Hz software cap, read_rgba_pixels signature, tab indentation in snippets, and rustdoc-style links that rendered literally are gone everywhere. CHANGELOG is restructured per Keep a Changelog with the missing entries (window_resizable, claims_raw_touch, Row::align_top/fill_height, caret fixes, dependency pins) and the pad_v Added/Changed contradiction resolved. New adaptive-layout API: ltk::orientation() with the Orientation enum, backed by viewport_size()/set_viewport_size — the runtime records the main surface's physical dimensions on every configure, before App::on_resize, so view() can branch a layout on portrait vs landscape without hand-tracking resizes. The portrait rule matches Length::orient (square counts as portrait); embedders driving core::UiSurface call set_viewport_size themselves. Documented in the crate root's responsive-design section and architecture.md. Fluid-vs-fixed sizing fixes in widgets, all the same disease — fluid content inside a fixed-pixel box. TextEdit::fixed_width takes impl Into<Length> (f32 call sites keep compiling as px) and the time picker's digit fields move to Length::fluid( 72.0 ), matching their fluid font so digits can no longer outgrow the box. Dialog::max_width takes impl Into<Length> with a Length::fluid( 480.0 ) default so the card scales with the stock buttons inside it, and the card's interior no longer stacks the column() default 16 px padding on top of CARD_PADDING — that double inset squeezed the action row until its buttons clipped on narrow windows. App::on_pointer_axis now triggers a view rebuild and repaint; previously state mutated in the hook did not paint until the next unrelated event. Examples reworked to be honest demos: responsive's mode/density controls become stock buttons in a grid/column so they follow the modes they demonstrate instead of overflowing; dialog's openers stack vertically, and the example gains the app-level ESC handler so the ESC chain closes an open dialog first and quits second; widgets' tab strip now switches real per-tab pages; carousel gains pointer/touch drag through the horizontal-swipe hooks (crustace's pager pattern), one-tile-per-detent mouse wheel, and snap math driven by the real surface width from on_resize instead of a hardcoded 800; clip_path arranges its cells by ltk::orientation() and sizes them from the counter-axis of the flow.
149 lines
5.7 KiB
Markdown
149 lines
5.7 KiB
Markdown
# Contributing to ltk
|
|
|
|
Thanks for considering a contribution. This document covers the practical
|
|
mechanics: how to set up your environment, how to run tests, what shape a
|
|
patch should take, and where to send it.
|
|
|
|
For background on the toolkit itself, read
|
|
[`docs/onboarding.md`](docs/onboarding.md) and
|
|
[`docs/architecture.md`](docs/architecture.md) first.
|
|
|
|
## Reporting bugs and proposing features
|
|
|
|
Open an issue on the project repository before sending a non-trivial
|
|
patch. We want to align on scope before you spend time on an
|
|
implementation. For security-relevant issues see
|
|
[`SECURITY.md`](SECURITY.md) — those should *not* go through the public
|
|
issue tracker.
|
|
|
|
When reporting a bug, include:
|
|
|
|
- the `ltk` version (commit hash if you built from source),
|
|
- the Rust toolchain (`rustc --version`),
|
|
- the compositor and OS,
|
|
- a minimal reproducer (Rust source preferred over screenshots),
|
|
- whether the issue happens on both the GLES and the software backend
|
|
(set `LTK_FORCE_SOFTWARE=1` to force software).
|
|
|
|
## Building and testing
|
|
|
|
The project requires the Rust toolchain shipped with Debian stable
|
|
(currently 1.85). On Debian / Ubuntu:
|
|
|
|
```bash
|
|
sudo apt-get install \
|
|
libwayland-dev libegl-dev libxkbcommon-dev pkg-config
|
|
|
|
git clone <repo>
|
|
cd ltk
|
|
cargo build
|
|
cargo test --features test-support
|
|
```
|
|
|
|
Tests require the `test-support` feature: the `test_support` module is
|
|
feature-gated in `src/lib.rs`, and the code under `tests/` and
|
|
`benches/` imports it, so a bare `cargo test` fails to compile.
|
|
|
|
The `Makefile` wraps the common targets:
|
|
|
|
```bash
|
|
make all # cargo build --release
|
|
make test # cargo test --features test-support
|
|
make doctest-md # typecheck the Rust snippets in docs/*.md
|
|
make audit # cargo audit (installs cargo-audit on first run)
|
|
make doc # cargo doc --no-deps
|
|
make examples # run every example under examples/ in turn
|
|
make clean # runs dh_clean, so it needs debhelper installed
|
|
```
|
|
|
|
Run `make doctest-md` after editing any file under `docs/` — it feeds
|
|
each markdown file to `rustdoc --test` to catch API drift in the
|
|
snippets.
|
|
|
|
Running the examples requires a Wayland session and the default theme
|
|
on disk:
|
|
|
|
```bash
|
|
export LTK_THEMES_DIR="$PWD/themes"
|
|
cargo run --example showcase
|
|
```
|
|
|
|
## Code style
|
|
|
|
`ltk` uses a custom **Modified Allman** style. `rustfmt`'s default
|
|
settings do not match it; do not run `cargo fmt`. The full rules live
|
|
in [`code_style_guide.md`](code_style_guide.md), but the headline points
|
|
are:
|
|
|
|
- **tabs** for indentation (never spaces),
|
|
- opening `{` on its **own new line** for `fn`, `impl`, `struct`,
|
|
`enum`, `mod`, `if`, `for`, `while`, `match`, `loop`,
|
|
- `} else {` and `} else if … {` on the same line as the closing brace
|
|
(compact else),
|
|
- spaces inside non-empty parentheses: `fn foo( x: i32 )`,
|
|
`bar( arg )`, `Some( x )`, `Ok( v )`,
|
|
- spaces inside non-empty attribute brackets: `#[ derive( Clone, Debug ) ]`,
|
|
- no spaces inside `<>` generics: `Vec<String>`, `Option<i32>`,
|
|
- comments in **English** — never another language.
|
|
|
|
Match the surrounding code when in doubt.
|
|
|
|
## Patch shape
|
|
|
|
- Keep changes focused: one logical change per pull request. A bug fix
|
|
and a refactor go in separate PRs.
|
|
- Add tests. The repository has ~680 tests covering the existing
|
|
surface, and a contribution that adds behaviour without test
|
|
coverage will get review pushback. See [`tests/`](tests/) for
|
|
examples of integration tests via `UiSurface`, and the inline
|
|
`#[cfg(test)] mod tests` blocks under `src/` for unit tests.
|
|
- Document new public API. Every `pub` item exported from the crate
|
|
root is expected to have a `///` rustdoc comment with at minimum a
|
|
one-paragraph description and an example. Module-level `//!`
|
|
comments are required for new submodules.
|
|
- Don't break the public API surface without coordinating. Until the
|
|
crate hits `1.0`, breaking changes go in minor versions
|
|
(`0.x.0 → 0.(x+1).0`); patch versions (`0.x.y → 0.x.(y+1)`) keep
|
|
source compatibility.
|
|
- Give user-visible changes a `CHANGELOG.md` entry under
|
|
`[Unreleased]`.
|
|
- Run `cargo test --features test-support` and `make audit` before
|
|
sending. CI will run them
|
|
again, but it is faster for both of us if your local run is clean.
|
|
|
|
## Architectural decisions worth knowing
|
|
|
|
A few patterns recur across the codebase:
|
|
|
|
- **Builder methods consume `self`** (`pub fn padding( mut self, p: impl Into<Length> ) -> Self`).
|
|
Chaining works because every builder returns `Self`. Don't introduce
|
|
setters that take `&mut self`.
|
|
- **Layouts and widgets share `Element<Msg>`.** Anything that converts
|
|
to `Element` can be pushed into any layout. The split between
|
|
[`src/layout/`](src/layout/) and [`src/widget/`](src/widget/) is
|
|
documentation, not architecture.
|
|
- **The runtime is single-threaded.** Use `RefCell` for caches inside
|
|
`App` state, never `Mutex`. Cross-thread communication goes through
|
|
[`ChannelSender`](src/app.rs).
|
|
- **`view()` must be pure.** No I/O, no allocation-heavy work, no
|
|
state mutation. Cache derived data on the app struct (behind
|
|
`RefCell` if needed) and look it up.
|
|
- **Theming is process-global.** There is no per-app theme; the active
|
|
document and mode live in a `RwLock<Arc<…>>`. `view()` reads the
|
|
state, never writes it. Mode flips and document swaps go through
|
|
`ltk::set_active_mode` and `ltk::set_active_document`.
|
|
- **Per-frame allocations are fine.** Building the `Element` tree on
|
|
every render is the supported model. Don't try to retain widgets
|
|
across frames.
|
|
|
|
## License
|
|
|
|
By submitting a patch you agree it is licensed under
|
|
[`LGPL-2.1-only`](LICENSE), the same as the rest of the project. Do not
|
|
add `Co-Authored-By` lines or other AI attribution to commit messages.
|
|
|
|
## Code of conduct
|
|
|
|
Be respectful. Disagreements are welcome; personal attacks are not.
|
|
Maintainers will moderate threads that go off the rails.
|