Code Review & Pull Request Process
Relevant source files
The following files were used as context for generating this wiki page:
The Code Review and Pull Request (PR) process in Kaleidux is a structured workflow designed to maintain high code quality, ensure stability of the main branch, and foster collaboration among contributors. The project operates on the principle that "main is sacred" and "all code changes go through pull requests," regardless of whether the contributor is a maintainer or an external developer.
Sources: PROJECT_STANDARDS.md:12-14, CONTRIBUTING.md:46-46
Core Philosophy and Branching Strategy
Kaleidux utilizes a tiered branching strategy to isolate development work from production-ready code. The workflow is designed to accommodate both intense "flow state" coding sessions and formal review processes.
Primary Branches
| Branch | Purpose | Push Policy |
|---|---|---|
main | Stable, production-ready code. Each commit is a tagged release. | Never push directly. Merge only from release branches. |
dev | Integration branch where all features are merged before release. | Never push directly. Receives merges from feature branches via PR. |
Sources: PROJECT_STANDARDS.md:41-45, CONTRIBUTING.md:162-166
Branching Flow
The following diagram illustrates the lifecycle of a change from a feature branch through to a production release on the main branch.
This diagram shows the isolation of features and the formal stabilization period during the release phase.
Sources: PROJECT_STANDARDS.md:88-103, CONTRIBUTING.md:173-195
Pull Request Lifecycle
1. Preparation and Submission
Before opening a PR, contributors must ensure their local branch is synchronized with the upstream dev branch to minimize merge conflicts.
- Rebase: Perform
git fetchandgit rebase origin/dev. - Cleanup: Use interactive rebase (
git rebase -i) to clean up "wip" or "temp" commits. - Verification: Run
cargo fmt,cargo clippy, andcargo test.
Sources: PROJECT_STANDARDS.md:118-132, CONTRIBUTING.md:237-251
2. Standard PR Requirements
Every PR must follow a specific template to provide context to reviewers. A critical requirement for external contributors is enabling the "Allow edits by maintainers" checkbox, allowing maintainers to resolve small conflicts or perform minor refactors directly.
| Template Section | Description |
|---|---|
| Summary | Brief description of the "what" and "why". |
| Changes | Bulleted list of specific implementation details. |
| Testing | Steps taken to verify the fix or feature (e.g., cargo run). |
| Breaking Changes | Explicit mention of any backward-incompatible changes. |
Sources: CONTRIBUTING.md:275-300, PROJECT_STANDARDS.md:154-180
3. Review and Collaboration
Reviews are treated as "conversations between equals" rather than bureaucratic hurdles. The goal is to improve code quality while maintaining the "Kaleidux type shi" ethos of high-performance aesthetic chaos.
- Review Roles: Maintainers provide final approval and merge; Collaborators review and test; Contributors respond to feedback.
- Feedback Etiquette: Reviewers are encouraged to provide the "why" behind suggestions and use questions rather than commands.
- Internal Merging: Maintainers may choose to merge a PR internally as part of a larger refactor. In such cases, the original contributor still receives full attribution in commit messages and release notes.
Sources: PROJECT_STANDARDS.md:195-212, PROJECT_STANDARDS.md:241-249, CONTRIBUTING.md:331-350
Commit Discipline
Kaleidux enforces Conventional Commits for the final history merged into dev and main. While "wip" commits are allowed during local development, they must be squashed or reworded before PR approval.
type(optional-scope): short description
[optional body]
[optional footer]
Common Types:
feat: New functionality (e.g.,feat(renderer): add bloom).fix: Bug fixes (e.g.,fix(ipc): handle timeouts).docs: Documentation only changes.refactor: Code restructuring without changing behavior.chore: Tooling or dependency updates.
Sources: PROJECT_STANDARDS.md:138-151, CONTRIBUTING.md:214-230
Release Management and Versioning
Only maintainers handle the transition from dev to main. This process involves creating a dedicated release/ branch to freeze the code for final validation.
Versioning Scheme
The project follows Semantic Versioning 2.0.0 with an optional codename. Codenames (e.g., kneecap) only change during MAJOR version bumps.
major.minor.patch-codename
Example: v0.0.1-kneecap (as seen in Cargo.toml).
Sources: PROJECT_STANDARDS.md:310-335, Cargo.toml:10-10
Release Flow Sequence
This sequence ensures that version increments are propagated back to the development environment.
Sources: PROJECT_STANDARDS.md:364-385, CONTRIBUTING.md:468-482
Summary
The Code Review & Pull Request process at Kaleidux balances rigid safety for production code with a flexible environment for development. By enforcing PRs for all changes, requiring conventional commits, and utilizing a robust branching strategy, the project ensures that the main branch remains a reliable record of high-performance, production-ready releases.
Sources: PROJECT_STANDARDS.md:440-447