Git Workflow & Branching Strategy

Relevant source files

The following files were used as context for generating this wiki page:

• PROJECT_STANDARDS.md
• CONTRIBUTING.md
• README.md
• kaleidux-daemon/src/main.rs
• kldctl/src/main.rs

Introduction

Kaleidux employs a structured Git workflow designed to maintain high stability for the main branch while allowing for "productive chaos" during development. The strategy emphasizes a clear separation between production-ready releases, integration testing, and feature development. By mandating pull requests (PRs) for all changes, the project ensures that code quality is maintained through review and automated checks before merging into core branches.

Sources: PROJECT_STANDARDS.md:1-25, CONTRIBUTING.md:1-10

Primary Branching Model

The project utilizes two permanent primary branches to manage the lifecycle of the software.

Branch	Purpose	Push Policy
main	Sacred, production-ready code. Every commit is a tagged release.	No direct pushes. Merges only from release branches.
dev	Integration branch. All features merge here first.	No direct pushes. Merges only via pull requests from feature branches.

Sources: PROJECT_STANDARDS.md:55-65, CONTRIBUTING.md:165-175

Branch Relationship Flow

The following diagram illustrates how code moves from local development through the integration phase to final production release.

Temporary Branch Types

Feature Branches

Used for all active development. Branches are created from dev and named according to their purpose:

• feat/name: New functionality.
• fix/name: Bug fixes.
• refactor/name: Code restructuring.
• docs/name: Documentation updates.
• chore/name: Tooling or dependency updates.

Sources: PROJECT_STANDARDS.md:67-78, CONTRIBUTING.md:177-187

Release Branches

Created from dev when a maintainer decides a release is ready. These branches are used to freeze the code, update version numbers in files like Cargo.toml, and perform final testing.
Sources: PROJECT_STANDARDS.md:80-91, CONTRIBUTING.md:189-195

Hotfix Branches

Created directly from main to address emergency production issues. Once the patch is verified, it is merged back into main (and tagged) and then merged into dev to ensure the fix persists in future releases.
Sources: PROJECT_STANDARDS.md:93-98, CONTRIBUTING.md:465-475

Pull Request (PR) Process

All changes enter the project via PRs. The process requires developers to clean their history and pass automated sanity checks before submission.

PR Requirements Checklist

1. Rebase: Feature branches must be rebased on the latest dev.
2. Commit Cleanup: History should be cleaned using git rebase -i.
3. Local Checks:
   • cargo fmt: Formatting check.
   • cargo clippy: Linting.
   • cargo test: Unit and integration tests.
   • cargo build --release: Build verification.

Sources: PROJECT_STANDARDS.md:135-155, CONTRIBUTING.md:255-270

PR Lifecycle

Commit Discipline

Kaleidux follows the Conventional Commits specification. While local development allows for "wip" or "temp" commits, the history must be polished before merging.

Commit Format

type(scope): description

Type	Meaning
feat	New feature
fix	Bug fix
perf	Performance improvement
refactor	Code change that neither fixes a bug nor adds a feature
docs	Documentation only
chore	Changes to build process or auxiliary tools

Sources: PROJECT_STANDARDS.md:160-185, CONTRIBUTING.md:235-250

Release Management & Versioning

Semantic Versioning

The project uses Semantic Versioning 2.0.0 (major.minor.patch-codename).

• MAJOR: Breaking changes (triggers a codename change).
• MINOR: New features (backward compatible).
• PATCH: Bug fixes.

Sources: PROJECT_STANDARDS.md:330-355, CONTRIBUTING.md:445-455

Release Procedure

1. Create release/vX.X.X from dev.
2. Update versioning in Cargo.toml, README.md, and man pages.
3. Merge to main and apply an annotated Git tag.
4. Merge release/vX.X.X back into dev to sync version bumps.
5. Delete the release branch.

Sources: PROJECT_STANDARDS.md:290-325, CONTRIBUTING.md:435-460

Exceptions: Direct to Main

Documentation-only changes (typos, grammar, clarifications in .md files) are the only changes permitted to be pushed directly to main. This is followed by an immediate sync merge into dev.
Sources: PROJECT_STANDARDS.md:115-130, CONTRIBUTING.md:150-160

Summary

The Kaleidux Git workflow provides a robust framework for high-performance software development. By using main as a stable release history and dev as a continuous integration target, the project ensures that aesthetic and technical standards are maintained through collaborative review and disciplined version management.