First commit. Version 0.1.0

2026-05-10 09:58:23 +02:00
parent af105b7f7d
commit bbab5e238d
635 changed files with 53627 additions and 175 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -0,0 +1,136 @@
+# 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
+```
+
+The `Makefile` wraps the common targets:
+
+```bash
+make all          # cargo build --release
+make test         # cargo test
+make audit        # cargo audit (installs cargo-audit on first run)
+make doc          # cargo doc --no-deps
+make example      # run every example under examples/ in turn
+make clean
+```
+
+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 ~400 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.
+- Run `cargo test` 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: f32 ) -> 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
+  [`crate::layout`] and [`crate::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
+  [`crate::set_active_mode`] and [`crate::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.