OpenLogi Contribution Workflow and Conventional Commit Format: A Complete Guide

OpenLogi requires contributors to use a strict conventional commit format (type(scope): description) and follow a six-step workflow defined in 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 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, 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.

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, this includes formatting checks, clippy lints, and unit tests.

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 explicitly states: always rebase, never merge.

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:

## 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 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 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.

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

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 describes helper commands for running CI checks locally. Use cargo xtask to replicate the exact environment used by GitHub Actions.

# Run specific CI jobs locally

cargo xtask ci clippy
cargo xtask ci test

For detailed environment setup and build instructions, consult docs/DEVELOPMENT.md.

CI Requirements and Automated Checks

The .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 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 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}