# OpenLogi Contribution Workflow and Conventional Commit Format: A Complete Guide

> Master the OpenLogi contribution workflow and conventional commit format. Follow our six-step guide for validated, rebased, and CI-gated pull requests to contribute effectively.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: how-to-guide
- Published: 2026-09-03

---

**OpenLogi requires contributors to use a strict conventional commit format (`type(scope): description`) and follow a six-step workflow defined in [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) that includes local validation, rebasing, and CI-gated pull requests.**

OpenLogi is a Rust-based open-source project that enforces reproducible contribution standards to maintain code quality. Understanding the **OpenLogi contribution workflow** and **conventional commit format** is essential for anyone submitting pull requests to the AprilNEA/OpenLogi repository. The entire process is documented in the repository's [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) file and secured by a comprehensive CI gate system.

## The Six-Step OpenLogi Contribution Workflow

The contribution process follows a strict, linear workflow designed to ensure clean git history and passing builds. According to [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md), contributors must complete these six stages before merging.

### 1. Branch Creation

All new work starts on a feature branch using the naming convention `type/kebab-description` branched directly from `master`. The prefix must match the conventional commit type (such as `feat/`, `fix/`, or `refactor/`), followed by a concise, hyphenated description.

```bash
git fetch upstream master
git checkout -b feat/openlogi-dpi upstream/master

```

### 2. Local Validation

Before any push, developers must run the **local gate** commands for every affected package. As specified in [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md), this includes formatting checks, clippy lints, and unit tests.

```bash
export RUSTFLAGS="-D warnings"
cargo fmt --all -- --check
cargo clippy -p openlogi-core --all-targets -- -D warnings
cargo test -p openlogi-core

```

### 3. Rebase Onto Master

OpenLogi mandates a rebase workflow. Contributors must fetch the latest `master` and rebase their feature branch to ensure linear history. The [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) explicitly states: always rebase, never merge.

```bash
git fetch upstream master
git rebase upstream/master

```

### 4. Pull Request Creation

Open a PR against `master` with two strict requirements:

- **Title**: Must follow conventional commit format (`type(scope): description`)
- **Body**: Must contain three sections: *Summary*, *Changes*, and *Testing*

Example PR body structure:

```markdown

## Summary

Add DPI stepper support to the core library.

## Changes

- New `DpiStep` enum and API.
- Updated config schema.

## Testing

`cargo test -p openlogi-core` passes on Linux and macOS.

Fixes #123

```

### 5. Automated CI Checks

The CI pipeline defined in [`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/workflows/ci.yml) runs the full workspace clippy, rustdoc checks, and platform-specific test suites. The PR must pass all jobs before merge.

### 6. Push Checklist

Before final submission, [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) requires a manual verification checklist:

- No merge conflict markers (`<<<<<<<`) remain
- Local gate is fully green
- All required CI jobs have been validated locally using `cargo xtask ci <job>`
- Cross-platform code audited if `#[cfg]` blocks were modified
- Versioned wire protocols and locale catalogs updated when applicable

## Conventional Commit Format Specification

OpenLogi enforces a strict conventional commit style that is parsed by automation. The format is defined in the *Git & GitHub* section of [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md).

### Structure and Syntax

Every commit message and PR title must follow this exact pattern:

```

type(scope): imperative lowercase description

```

- **Type**: One of `feat`, `fix`, `refactor`, `chore`, `docs`, `ci`, `perf`, `style`, `build`, `test`
- **Scope**: Either a crate short name (`gui`, `agent`, `hidpp`, `core`) or a cross-cutting concern (`release`, `ci`, `i18n`, `windows`, `linux`, `macos`, `tray`, `infra`)
- **Description**: Concise, imperative phrase in lowercase (e.g., "add dpi stepper", not "added dpi stepper")

### Valid Examples

```bash
git commit -m "feat(openlogi-core): add DPI stepper support"
git commit -m "fix(gui): resolve tray icon flicker on macOS"
git commit -m "docs(agent): clarify HID++ protocol documentation"

```

## Local Development and Validation

The [`xtask/README.md`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/README.md) describes helper commands for running CI checks locally. Use `cargo xtask` to replicate the exact environment used by GitHub Actions.

```bash

# Run specific CI jobs locally

cargo xtask ci clippy
cargo xtask ci test

```

For detailed environment setup and build instructions, consult [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md).

## CI Requirements and Automated Checks

The [`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/workflows/ci.yml) file defines mandatory checks including:

- Full workspace clippy with warnings-as-errors
- Documentation generation (`rustdoc`)
- Cross-platform test matrices (Linux, macOS, Windows)
- Formatting verification

Pull requests cannot be merged until all status checks pass.

## Summary

- Branch names must follow `type/kebab-description` format branched from `master`
- Local gate commands (`cargo fmt`, `clippy`, `test`) must pass before every push
- Rebase workflow is mandatory; merge commits are not allowed
- Commit messages and PR titles must use `type(scope): imperative description` format
- Allowed types include `feat`, `fix`, `refactor`, `chore`, `docs`, `ci`, `perf`, `style`, `build`, `test`
- PR bodies require *Summary*, *Changes*, and *Testing* sections
- CI checks defined in [`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/workflows/ci.yml) gate all merges

## Frequently Asked Questions

### What is the exact branch naming convention for OpenLogi?

Branches must use the format `type/kebab-description` where the type matches a conventional commit prefix (`feat`, `fix`, etc.) and the description uses lowercase words separated by hyphens. For example, `feat/dpi-support` or `fix/tray-linux`. This is defined in [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) at line 52.

### What types are allowed in the conventional commit format?

OpenLogi recognizes ten specific types: `feat` for features, `fix` for bug fixes, `refactor` for code restructuring, `chore` for maintenance, `docs` for documentation, `ci` for continuous integration, `perf` for performance improvements, `style` for formatting, `build` for build system changes, and `test` for test additions.

### How do I run the local gate before pushing?

Set `RUSTFLAGS="-D warnings"` and execute `cargo fmt --all -- --check`, `cargo clippy` for your specific package with `--all-targets`, and `cargo test` for the affected crates. For comprehensive validation, use `cargo xtask ci <job>` as documented in [`xtask/README.md`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/README.md).

### What should be included in a pull request body?

Every PR body must contain three sections: **Summary** (what and why), **Changes** (technical details of the implementation), and **Testing** (how you verified the changes). This structure allows reviewers to quickly assess impact and verification coverage without reading the full diff.