Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
138 lines (103 loc) · 4.65 KB

CONTRIBUTING.md

File metadata and controls

138 lines (103 loc) · 4.65 KB

Contributing to SLT

Before contributing, read:

Getting Started

git clone https://github.com/subinium/SuperLightTUI.git
cd superlighttui
cargo test
cargo run --example demo

Development

Build

cargo build
cargo build --features async

Test

cargo test --all-features
cargo clippy --all-features -- -D warnings

Run Examples

cargo run --example hello
cargo run --example counter
cargo run --example demo
cargo run --example inline
cargo run --example anim
cargo run --example async_demo --features async

Quality Gate (run ALL before submitting)

cargo fmt -- --check
cargo check --all-features
cargo clippy --all-features -- -D warnings
cargo test --all-features
cargo check --examples --all-features

Pull Requests

  • Use Conventional Commits: feat:, fix:, refactor:, docs:, chore:, test:
  • Run the full quality gate above before submitting
  • One logical change per PR
  • Add examples for new widgets
  • The PR template includes a checklist — complete it

Code Style

  • No unsafe code — enforced by #![forbid(unsafe_code)]
  • No unwrap() in functions returning Result — enforced by lint
  • No println!()/eprintln!()/dbg!() in library code — enforced by lint
  • No unnecessary comments — code should be self-documenting
  • Use self.theme.X for colors, never hardcode

Adding a Widget

Follow this checklist when adding a new widget:

  1. State struct in widgets.rs — name it {Widget}State, implement Default
  2. State placement in the matching src/widgets/*.rs group file, then surfaced through src/widgets.rs
  3. Rendering method on Context in the matching src/context/widgets_*/ subfile (widgets_input/, widgets_display/, widgets_interactive/, or widgets_viz.rs)
  4. Re-export in lib.rs
  5. Doc comment (///) on the public method with usage example
  6. Response pattern — interactive widgets return Response, display widgets return &mut Self
  7. Focus — call register_focusable() if the widget accepts keyboard input
  8. Events — consume handled key events so they don't bubble
  9. Theme — use self.theme.* for default colors
  10. Example — add to an existing example or create a new one

Error Handling

See docs/DESIGN_PRINCIPLES.md — Error Handling for the full policy.

Summary:

  • Use io::Result for fallible operations
  • panic!() only for programmer errors (with descriptive messages)
  • No custom error types — io::Error is sufficient for SLT's error paths

Architecture

See docs/ARCHITECTURE.md for the full module map and data flow.

User closure → Context collects Commands → build_tree() → flexbox compute → render to Buffer → diff → flush
  • Immediate mode: Each frame, the closure runs and describes the UI
  • Double buffer: Previous and current buffers are diffed, only changes are flushed
  • Flexbox: Row/column layout with gap, grow, shrink
  • One-frame delay: Layout-computed data (focus count, scroll bounds, hit areas) feeds back to the next frame via prev_* fields

Releasing

Releases are automated via GitHub Actions. To publish a new version:

# 1. Bump version in Cargo.toml
# 2. Update CHANGELOG.md with new section
# 3. Commit and push
git add Cargo.toml Cargo.lock CHANGELOG.md
git commit -m "chore: release vX.Y.Z"
git push

# 4. Tag triggers the release pipeline
git tag vX.Y.Z
git push --tags

The release workflow (.github/workflows/release.yml) will:

  1. Run full CI (check, test, clippy, fmt) on stable + MSRV 1.81
  2. Verify tag matches Cargo.toml version
  3. Publish to crates.io
  4. Create GitHub Release with notes extracted from CHANGELOG.md

Do not run cargo publish manually — let the workflow handle it.

Dependencies

Core: unicode-width, compact_str. Terminal I/O: crossterm (default feature). Optional: tokio (async), serde, image, qrcode, flate2 (kitty-compress), tree-sitter syntax features.

Do not add new dependencies without discussion. See docs/DESIGN_PRINCIPLES.md — Dependencies.