# OpenLogi Project Development Process: Verification Steps and CI Workflow > Discover the OpenLogi project development process including its three-tiered verification workflow. Learn about local checks, affected package testing, and CI gates for code quality. - Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi) - Tags: how-to-guide - Published: 2026-08-27 --- **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](https://github.com/AprilNEA/OpenLogi) repository maintains strict verification standards through a multi-layered approach defined in [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) and [`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.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`](https://github.com/AprilNEA/OpenLogi/blob/main/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: ```bash # Check only the core crate cargo check -p openlogi-core # Run a specific test filter cargo test -p openlogi-core ``` 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`](https://github.com/AprilNEA/OpenLogi/blob/main/rust-toolchain.toml). For local iteration, run Clippy only on touched crates: ```bash 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`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/workflows/ci.yml). ### Formatting Verification Before any commit, the code must satisfy `rustfmt` requirements: ```bash 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`](https://github.com/AprilNEA/OpenLogi/blob/main/Cargo.toml) or [`rust-toolchain.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/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: ```bash cargo tree --invert ``` 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: ```bash 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`](https://github.com/AprilNEA/OpenLogi/blob/main/.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`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) and implemented in [`.github/workflows/ci.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/.github/workflows/ci.yml), the complete verification suite includes: ```bash 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: ```bash 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`](https://github.com/AprilNEA/OpenLogi/blob/main/.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`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) files and `.claude/rules/` directory. ### Wire-Format Changes Modifications to inter-process communication require version bumps and format testing: ```bash # After bumping PROTOCOL_VERSION cargo test -p openlogi-ipc --test wire_format ``` This validation, documented in [`crates/openlogi-ipc/AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/AGENTS.md), ensures protocol compatibility across versions. ### Internationalization Updates Locale file changes must maintain key consistency with [`en.yml`](https://github.com/AprilNEA/OpenLogi/blob/main/en.yml): ```bash cargo test -p openlogi-desktop i18n ``` The [`.claude/rules/i18n.md`](https://github.com/AprilNEA/OpenLogi/blob/main/.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`](https://github.com/AprilNEA/OpenLogi/blob/main/.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`](https://github.com/AprilNEA/OpenLogi/blob/main/.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`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/main.rs) to replicate CI behavior locally: ```bash # 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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/.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`](https://github.com/AprilNEA/OpenLogi/blob/main/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 `, then run targeted verification with `cargo test -p -p `. 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`](https://github.com/AprilNEA/OpenLogi/blob/main/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.