Contributing to Sentinel

Relevant source files

The following files were used as context for generating this wiki page:

• CODE_OF_CONDUCT.md
• rustfmt.toml
• Cargo.toml
• README.md
• IMPLEMENTATION_PLAN.md
• crates/sentinel/Cargo.toml
• crates/sentinel/src/lib.rs

Welcome to the Sentinel project! We are building the gold standard for transparent, auditable data storage, and we welcome all contributions. This project is ambitious, and your help is needed to create a new kind of database for organizations that prioritize accountability and transparency. This guide provides all the information you need to get started with your contributions.

The project's core philosophy is "Filesystem is the Database," leveraging OS reliability and standard UNIX tools. Contributions should align with these design principles, focusing on security, immutability, and simplicity. For a detailed overview of the architecture and future plans, please see the Implementation Plan.

Sources: README.md:195-203, README.md:94-98

Code of Conduct

All contributors are expected to adhere to the Contributor Covenant Code of Conduct. We are committed to providing a harassment-free experience for everyone. The goal is to foster an open, welcoming, diverse, inclusive, and healthy community.

Sources: CODE_OF_CONDUCT.md:3-12

Our Standards

Examples of expected behavior include:

• Demonstrating empathy and kindness.
• Being respectful of differing opinions and experiences.
• Giving and gracefully accepting constructive feedback.
• Accepting responsibility and learning from mistakes.

Unacceptable behavior includes trolling, harassment, personal attacks, and the use of sexualized language.

Sources: CODE_OF_CONDUCT.md:14-35

Enforcement

Instances of unacceptable behavior can be reported to community leaders at support@cyberpath-hq.com. All complaints will be investigated promptly and fairly. Community leaders have the responsibility to remove, edit, or reject contributions that do not align with the Code of Conduct.

The following diagram illustrates the enforcement process based on community impact.

This diagram shows the tiered consequences for violations of the Code of Conduct.

Sources: CODE_OF_CONDUCT.md:46-60, CODE_OF_CONDUCT.md:62-92

Getting Started

To start contributing, you'll need to set up your local development environment.

1. Clone the repository:

   git clone https://github.com/cyberpath-HQ/sentinel
   cd sentinel
   

2. Build the project:
   The project is built using Cargo. To create a release build, run:

   cargo build --release
   

Sources: README.md:76-79

Project Structure

Sentinel is organized as a Cargo workspace. The main application crates are located in the crates/ directory.

[workspace]
resolver = "2"
members = [
    "crates/*"
]

The sentinel crate is a key part of this workspace.

[package]
name = "sentinel"
authors.workspace = true
edition.workspace = true
rust-version.workspace = true
version.workspace = true
readme.workspace = true

Sources: Cargo.toml:1-4, crates/sentinel/Cargo.toml:1-7

Running Tests

The project includes a basic test suite. You can run tests using Cargo.

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() {
        let result = add(2, 2);
        assert_eq!(result, 4);
    }
}

Sources: crates/sentinel/src/lib.rs:3-11

Coding Standards

To maintain code quality and consistency, the project enforces strict formatting and linting rules.

Code Formatting

The project uses rustfmt with a detailed configuration to ensure a consistent code style. All contributions must be formatted according to the rules in rustfmt.toml.

Key formatting rules are summarized below:

Setting	Value	Description
max_width	120	The maximum line width.
brace_style	SameLineWhere	Braces are on the same line, except for where clauses.
control_brace_style	ClosingNextLine	The closing brace of a control-flow block is on the next line.
trailing_comma	Vertical	A trailing comma is added where a newline exists.
group_imports	StdExternalCrate	Groups imports into std, external, and crate sections.
reorder_imports	true	Automatically reorders use statements.
use_field_init_shorthand	true	Enforces shorthand for struct field initialization.
edition	2021	The Rust edition to use for formatting.

Sources: rustfmt.toml:1-77

Linting with Clippy

The project uses an extensive set of Clippy lints to enforce high-quality, robust, and performant code. The configuration in Cargo.toml sets many powerful lints to deny, which will cause the build to fail if they are violated.

The general workflow for ensuring code quality is as follows:

This diagram shows the required steps before submitting code for review.

Sources: Cargo.toml:13-455

Key linting rules include:

• panic = "deny": The application will not compile if panic! is used. It must abort.
• unimplemented = "deny" and todo = "deny": All code must be fully implemented.
• unwrap_used = "allow": While discouraged, unwrap() is currently allowed. This may change.
• print_stdout = "deny" and print_stderr = "deny": Direct printing to standard streams is forbidden.
• missing_docs_in_private_items = "warn": All items, even private ones, should be documented.
• missing_safety_doc = "deny": All unsafe blocks must have a safety doc comment.
• integer_division = "allow" and float_arithmetic = "allow": These are permitted but should be used with care.

Sources: Cargo.toml:13-455

Release Profile

The release build is highly optimized for performance, security, and a small binary size.

[profile.release]
codegen-units = 1           # Single codegen unit for better optimizations
debug = false               # No debug info for smaller and faster binary
lto = true                  # Link Time Optimization for better codegen
debug-assertions = false    # Disable debug assertions to avoid runtime overhead
incremental = false         # Disable incremental for clean, reliable release builds
opt-level = 3               # Max optimization level
panic = "abort"             # Abort on panic, no unwinding, smaller binary and better security
overflow-checks = false     # Disable integer overflow checks to enhance performance
strip = true                # Strip symbols to reduce binary size

These settings ensure that production builds are as efficient and secure as possible.

Sources: Cargo.toml:8-17

Areas for Contribution

We welcome contributions across all areas of the project. The implementation is planned in phases, offering opportunities for contributors with various interests and skill levels.

Feature Area	Phase	Priority	Example Tasks
Core DBMS	1	P0	Document CRUD, Soft Deletes, Basic Filtering
Durability & Concurrency	2	P0	Write-Ahead Logging (WAL), File Locking, Transactions
Performance & Scale	3	P1	LRU Caching, Hash & B-tree Indices
Encryption & Security	4	P1	AES-256 Encryption, Digital Signatures
Replication & Distribution	5	P1	Git-Based Replication, Raft Consensus
Compliance & Audit	6	P1	Immutable Audit Trails, Compliance Reporting
Advanced Features	7	P2	Full-Text Search, MVCC, Merkle Trees

Sources: IMPLEMENTATION_PLAN.md:374-391, README.md:104-133

Help is particularly needed with:

• Core DBMS features (transactions, indexing, caching)
• Encryption and security implementations
• Performance optimization and benchmarking
• Documentation and tutorials

Sources: README.md:186-192

Summary

Contributing to Sentinel means helping to build a new foundation for trusted data systems. By following the guidelines in this document, you can ensure your contributions are effective and align with the project's goals. We look forward to your pull requests, issues, and discussions.