Contribution Guide
Relevant source files
The following files were used as context for generating this wiki page:
The Kaleidux Contribution Guide outlines the standards, workflows, and technical requirements for developers looking to improve the high-performance, hardware-accelerated wallpaper daemon. The project emphasizes a "Kaleidux type shi" philosophy—balancing high-performance aesthetic chaos with strict Git discipline to maintain stable, cyberpunk-adjacent desktop experiences.
This guide serves as a manual for both external contributors and maintainers, ensuring that all code changes—from GLSL shader transitions to IPC protocol updates—follow a unified integration process.
Sources: CONTRIBUTING.md:1-12, PROJECT_STANDARDS.md:10-25, README.md:1-15
Development Environment Setup
Kaleidux is built using the Rust programming language and utilizes WGPU for hardware acceleration and GStreamer for video processing.
Prerequisites and Build Requirements
Contributors must use Rust 1.89+ stable (nightly is explicitly not supported). The following system dependencies are required for development:
| Dependency | Purpose |
|---|---|
| Rust 1.89+ | Core language runtime (Stable) |
| GStreamer 1.20+ | Video playback logic (plugins: good, bad, libav) |
| Vulkan/GPU Drivers | WGPU hardware acceleration |
| Wayland/X11 Headers | Backend windowing system protocols |
| pkgconf / cmake | Build-time dependency management |
Sources: CONTRIBUTING.md:38-60, README.md:73-85, Cargo.toml:1-10
Workspace Structure
The project is organized as a Cargo workspace with three primary members:
- kaleidux-daemon: The core background service handling rendering and display interoperability.
- kldctl: A CLI utility for interacting with and controlling the daemon.
- kaleidux-common: Shared types, IPC protocol definitions, and transition logic.
Sources: CONTRIBUTING.md:103-120, Cargo.toml:1-6
Git Workflow and Branching Strategy
Kaleidux employs a strict branching strategy where the main branch is considered sacred and contains only tagged, production-ready releases.
Branch Taxonomy
| Branch Type | Naming Convention | Description |
|---|---|---|
| Main | main | Production releases only. Never push directly. |
| Integration | dev | All features merge here via PR. Primary development target. |
| Feature | feat/name | New functionality or features. |
| Fix | fix/name | Bug fixes and patches. |
| Release | release/version | Isolation for version bumps and final testing. |
Sources: CONTRIBUTING.md:158-185, PROJECT_STANDARDS.md:52-85
Development Lifecycle
The following diagram illustrates the lifecycle of a contribution from local development to a production release on main.
The workflow ensures that dev remains the integration point while main maintains immutable history.
Sources: PROJECT_STANDARDS.md:105-130, CONTRIBUTING.md:188-215
Code Standards and Quality
Commit Discipline
The project follows Conventional Commits. While "wip" commits are allowed during local development, history must be cleaned using git rebase -i before submitting a Pull Request.
Common Types:
feat: New feature (e.g.,feat(renderer): add bloom effect)fix: Bug fix (e.g.,fix(ipc): handle socket timeouts)refactor: Code restructuring without behavior changesperf: Performance improvementsdocs: Documentation only changes
Sources: CONTRIBUTING.md:255-275, PROJECT_STANDARDS.md:162-185
Technical Requirements
All contributions must meet the following criteria before being considered for merge:
- Formatting: Must pass
cargo fmt. - Linting: Must pass
cargo clippy -- -D warnings(zero warnings allowed). - Testing: Must pass all unit and integration tests via
cargo test. - Error Handling: Utilize the
Resulttype and?operator for error propagation, providing context for failures. - Documentation: Public APIs must be documented explaining why a piece of code exists, not just what it does.
Sources: CONTRIBUTING.md:377-410, PROJECT_STANDARDS.md:300-315, kaleidux-daemon/src/main.rs:175-195
Pull Request and Review Process
Submitting Changes
Pull Requests (PRs) must target the dev branch. Contributors are encouraged to open "Draft" PRs for early architectural feedback or when working on large features.
Mandatory PR Template Sections:
- Summary: Brief description of changes.
- Testing: Steps taken to verify the code (e.g.,
cargo build --release). - Breaking Changes: Identification of any API or config changes.
- Related Issues: Link to GitHub issues (e.g.,
Closes #42).
Sources: CONTRIBUTING.md:300-335, PROJECT_STANDARDS.md:195-215
Review Interaction
The review process is viewed as a conversation between equals.
- Maintainer Role: Final review, merge approval, and release tagging.
- Feedback: Reviewers provide "blocking" or "non-blocking" feedback.
- Internal Merging: Maintainers may integrate a PR internally during large refactors while ensuring the original author receives full credit in release notes and commit history.
Release and Versioning
Semantic Versioning
Kaleidux uses Semantic Versioning 2.0.0 (MAJOR.MINOR.PATCH) combined with a codename. Codenames only change on MAJOR version bumps. The current version series is kneecap (e.g., 0.0.1-kneecap).
Sources: PROJECT_STANDARDS.md:365-385, Cargo.toml:8
Documentation Exception
Documentation-only changes (typos, .md file formatting) that do not affect code logic are the only changes permitted to be pushed directly to main by maintainers, followed by an immediate sync to dev.
Sources: CONTRIBUTING.md:135-155, PROJECT_STANDARDS.md:88-103
The Kaleidux contribution process is designed to support high-performance development through rigorous automated checks and clear communication, ensuring the project's "Aesthetic Excellence" remains uncompromised.
Sources: CONTRIBUTING.md:412-422, PROJECT_STANDARDS.md:465-475