OpenLogi Project Development Process: Verification Steps and CI Workflow

The OpenLogi project employs a three-tiered verification workflow that combines local fast-path checks, affected-package testing, and comprehensive CI gates to ensure code quality across Rust workspaces.

The AprilNEA/OpenLogi repository maintains strict verification standards through a multi-layered approach defined in AGENTS.md and .github/workflows/ci.yml. This OpenLogi project development process splits validation into distinct tiers, allowing developers to iterate quickly while guaranteeing workspace-wide stability. Every change must pass through local checks, package-specific verification, and finally the full CI matrix before merging.

The Three-Tier Verification Strategy

OpenLogi organizes its quality assurance into three progressive tiers designed to balance developer velocity with system reliability. As documented in the root AGENTS.md, these tiers move from focused local checks to exhaustive continuous integration:

1. Local fast-path: Immediate feedback during coding
2. Affected-package: Targeted validation for isolated changes
3. Full-tier: Comprehensive workspace verification required for rebases and wide-ranging modifications

This structure ensures that developers receive rapid feedback during the inner development loop while preventing regressions through rigorous automated gates.

Local Fast-Path Checks (Inner Development Loop)

During active development, OpenLogi contributors run focused commands that complete in seconds. These local fast-path checks target specific crates rather than the entire workspace.

Proof-of-Concept Testing

The fastest validation selects the smallest test or compile target to prove a change works. Rather than building everything, developers run:

# Check only the core crate

cargo check -p openlogi-core

# Run a specific test filter

cargo test -p openlogi-core <test-filter>

This approach avoids the overhead of unrelated crates while confirming basic correctness.

Focused Linting with Clippy

OpenLogi enforces strict linting standards via rust-toolchain.toml. For local iteration, run Clippy only on touched crates:

cargo clippy -p openlogi-core --all-targets -- -D warnings

The -D warnings flag (set via RUSTFLAGS="-D warnings" in CI) treats all warnings as errors, matching the strict standards enforced in .github/workflows/ci.yml.

Formatting Verification

Before any commit, the code must satisfy rustfmt requirements:

cargo fmt --all -- --check

This ensures consistency across the workspace and prevents formatting-related CI failures.

Affected-Package Verification (Pre-Push Tier)

When changes remain isolated to specific crates without modifying workspace-wide inputs (like Cargo.toml or rust-toolchain.toml), OpenLogi supports affected-package verification. This tier limits testing to the dependency graph of modified crates.

Deriving the Affected Set

Use cargo tree to identify downstream dependencies:

cargo tree --invert <changed-crate>

This lists every crate that depends on the modified package, ensuring you test all potentially impacted code paths.

Running Targeted Verification

Execute formatting, linting, and testing only on the affected packages:

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

According to .claude/rules/rust.md, this approach guarantees downstream crates still compile and pass their own test suites without waiting for the full workspace build.

Full-Tier Verification (Workspace-Wide CI Gate)

The full-tier verification represents the definitive quality gate. Required for rebases, workspace-wide changes, or when affected-package derivation fails, this process validates every crate in the repository.

Core Full-Tier Commands

As defined in AGENTS.md and implemented in .github/workflows/ci.yml, the complete verification suite includes:

export RUSTFLAGS="-D warnings"
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

Documentation Validation

OpenLogi includes a specialized rustdoc job that catches broken intra-doc links invisible to the compiler or Clippy:

RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps \
  --document-private-items \
  --exclude openlogi-ui --exclude openlogi-desktop \
  --exclude openlogi-overlay --exclude openlogi-agent

The exclusions prevent pulling in heavy graphics toolchains for the GUI crates, optimizing CI runtime while maintaining documentation quality standards.

Continuous Integration Pipeline

The authoritative gate for the OpenLogi project development process resides in .github/workflows/ci.yml. This GitHub Actions workflow runs the full-tier verification plus platform-specific checks that cannot be tested locally in a single environment.

Core CI Jobs

The CI matrix includes these verification stages:

• Linux clippy: Primary linting on the default target
• macOS + Linux MSRV: Building with minimum supported Rust version (1.98)
• rustdoc: Documentation link verification and completeness
• Linux tests (no desktop): Unit and integration tests excluding GUI requirements
• macOS --all-targets tests: Full test suite including GUI crates on macOS
• typos: Spell-checking of source code and documentation
• cargo-deny: License compliance and security auditing of dependencies
• Windows clippy: Cross-platform lint validation
• wasm portability: Ensuring WebAssembly build compatibility
• shell lint: Validation of repository shell scripts

Only when all jobs report success may a branch merge into the main branch.

Special-Case Verifications

Certain modifications trigger additional special-case verifications documented in per-crate AGENTS.md files and .claude/rules/ directory.

Wire-Format Changes

Modifications to inter-process communication require version bumps and format testing:

# After bumping PROTOCOL_VERSION

cargo test -p openlogi-ipc --test wire_format

This validation, documented in crates/openlogi-ipc/AGENTS.md, ensures protocol compatibility across versions.

Internationalization Updates

Locale file changes must maintain key consistency with en.yml:

cargo test -p openlogi-desktop i18n

The .claude/rules/i18n.md file defines requirements for ensuring every locale file contains the same translation keys as the English reference.

Cross-Platform Code Modifications

When editing #[cfg(target_os = …)] blocks, OpenLogi requires manual audit or cross-linting per .claude/rules/cross-platform.md. This prevents platform-specific regressions in a multi-OS codebase.

macOS Privacy Permissions

Changes to privacy-related code require following the macOS-specific skill guide at .claude/skills/openlogi-macos-permissions/SKILL.md, ensuring proper handling of system permissions.

Running Verification Locally

OpenLogi provides the xtask utility in xtask/src/main.rs to replicate CI behavior locally:

# Run the full CI matrix locally

cargo xtask ci

# Run specific CI jobs

cargo xtask ci clippy
cargo xtask ci rustdoc

This helper binary executes the same commands defined in ci.yml, enabling developers to debug CI failures without pushing to remote branches.

Summary

• OpenLogi implements a three-tier verification system: local fast-path, affected-package testing, and full-tier workspace validation.
• Local development relies on cargo check, focused cargo clippy, and cargo fmt for rapid iteration.
• The affected-package tier uses cargo tree --invert to limit testing to impacted dependency graphs.
• Full-tier verification runs --workspace commands and includes rustdoc link checking with specific exclusions for GUI crates.
• .github/workflows/ci.yml orchestrates the authoritative CI gate with platform-specific jobs including MSRV, WASM, and cargo-deny audits.
• Special cases like wire-format changes (openlogi-ipc) and i18n updates (openlogi-desktop) follow documented procedures in AGENTS.md and .claude/rules/.

Frequently Asked Questions

What is the minimum Rust version required for OpenLogi development?

OpenLogi maintains a minimum supported Rust version (MSRV) of 1.98, verified through dedicated CI jobs on both macOS and Linux. Developers should verify their changes compile with this version using the affected-package or full-tier commands before submitting pull requests.

How do I run only the tests affected by my changes?

First, identify dependent crates using cargo tree --invert <your-crate>, then run targeted verification with cargo test -p <crate1> -p <crate2>. This limits the feedback loop to relevant code paths without building unrelated workspace members. For convenience, the cargo xtask utility can automate this derivation.

Why does the documentation build exclude certain crates?

The cargo doc command excludes openlogi-ui, openlogi-desktop, openlogi-overlay, and openlogi-agent to avoid pulling in heavy graphics toolchains during CI. These GUI crates require specific graphics dependencies that would unnecessarily slow down the documentation verification job, while their public APIs are documented through other means.

What happens if I modify the wire protocol between components?

Any change to the IPC wire format requires bumping PROTOCOL_VERSION (as documented in crates/openlogi-ipc/AGENTS.md) and running cargo test -p openlogi-ipc --test wire_format. This ensures backward compatibility and protocol stability across different versions of the application components.

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