Contributing Guide
Relevant source files
The following files were used as context for generating this wiki page:
This guide outlines the standards, processes, and technical requirements for contributing to Horizon, a self-hostable Configuration Management Database (CMDB). It covers everything from setting up your development environment to adhering to specific coding styles and security practices.
All contributors are expected to uphold the Contributor Covenant Code of Conduct, which pledges a harassment-free experience for everyone regardless of background or level of experience.
Sources: README.md:144-150, CODE_OF_CONDUCT.md:3-12
Getting Started
Development Environment Setup
The Horizon project requires specific toolchains and infrastructure to be in place before development can begin.
- Rust Version: Minimum
1.94.0-nightly. The project consistently uses the latest stable or nightly versions. - Infrastructure: Requires PostgreSQL (latest stable) and Redis (latest stable).
- Containers: Docker and Docker Compose are required for the containerized development environment.
Sources: README.md:104-109, IMPLEMENTATION_PLAN.md:46-47
Workflow for Submitting Changes
- Fork the repository and create a feature branch (e.g.,
feature/amazing-feature). - Development: Implement changes following the Code Style Guidelines.
- Validation: Ensure all quality gates (compilation, linting, tests) pass.
- Submission: Push to your branch and open a Pull Request.
Sources: README.md:152-160
Development Infrastructure
The project provides automation scripts to manage the lifecycle of the development environment.
Docker Development Services
The scripts/docker-dev.sh utility manages the local infrastructure needed for the API server.
The script manages volumes for PostgreSQL, Redis, and pgAdmin, ensuring persistent data during development.
Sources: scripts/docker-dev.sh:44-119
Build and Testing Commands
Contributors should use the following standard commands for development:
| Command | Purpose |
|---|---|
cargo build | Build the entire workspace |
cargo test --all-features | Run all workspace tests |
cargo clippy --all-features | Run lints with all features enabled |
cargo fmt --all | Format all code according to rustfmt.toml |
./scripts/run_coverage.sh | Generate test coverage reports |
Sources: AGENTS.md:11-37, AGENTS.md:146-152
Code Style Guidelines
Formatting and Imports
Horizon enforces strict formatting to maintain a clean codebase:
- Indentation: 4 spaces, no tabs.
- Line Width: Maximum 120 characters for code, 100 for comments.
- Import Ordering:
StdExternalCrate(Standard library → External crates → Local parent/crate modules). - Granularity: Crate-level imports are preferred (
imports_granularity = "Crate").
Sources: AGENTS.md:41-61
Naming Conventions
| Item | Convention | Example |
|---|---|---|
| Structs/Enums/Traits | PascalCase | UserProfile, AssetType |
| Functions/Variables | snake_case | validate_input, user_id |
| Constants | SCREAMING_SNAKE_CASE | MAX_CONNECTIONS |
Sources: AGENTS.md:65-74
Error Handling
Developers must use the AppError enum from the error crate, utilizing thiserror for variant definition and anyhow for context-rich propagation.
async fn get_user(id: &str) -> Result<User> {
let user = db.find_user(id).await?;
user.ok_or_else(|| AppError::not_found("User"))
}
Sources: AGENTS.md:78-90
Testing and Quality Gates
Quality Requirements
No task is considered complete until it satisfies the Quality Gate:
- Compilation:
cargo build --all-featuresmust pass. - Testing: Every function requires unit tests, covering edge cases and invalid data.
- Coverage: Minimum 90% test coverage is required.
- Coverage Tool: Use
./scripts/run_coverage.sh. The project specifically forbidscargo tarpaulindue to reliability issues. - Documentation:
cargo doc --all-features --no-depsmust build without errors. All public APIs require///doc comments.
Sources: AGENTS.md:110-128, AGENTS.md:146-155, scripts/run_coverage.sh:10-25
Coverage Workflow
The run_coverage.sh script executes the following flow:
Sources: scripts/run_coverage.sh:17-30
Security Standards
Contributors must adhere to "defense-in-depth" security measures:
- Sensitive Data: Use
zeroizefor clearing sensitive data from memory. - Encryption: Use
XChaCha20-Poly1305for symmetric encryption andArgon2idfor password hashing via theRustCryptocrates. - Secrets: Never hardcode secrets; use environment variables or secure configuration providers.
- Signatures: Use
Ed25519for digital signatures andmTLSfor communication.
Sources: README.md:164-173, IMPLEMENTATION_PLAN.md:65-76, AGENTS.md:130-134
Project Structure Reference
When contributing, place new modules in the appropriate workspace member:
| Crate Path | Responsibility |
|---|---|
crates/api-server/ | REST API logic and web routes |
crates/agent/ | Cross-platform collection agent |
crates/database/ | Database layer and Sea-ORM entities |
crates/cli/ | Command-line management tools |
crates/error/ | Shared error types and API response wrappers |
crates/ui/ | React-based frontend and Tauri desktop wrapper |
Sources: README.md:120-130, IMPLEMENTATION_PLAN.md:58-63
Summary
Contributing to Horizon requires a commitment to high-quality Rust code, comprehensive testing, and strict security practices. By following the standardized build commands, adhering to the naming and formatting conventions, and ensuring 90% test coverage, contributors help maintain a robust and secure IT infrastructure management system.