Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
345 lines (252 loc) · 7.4 KB

CONTRIBUTING.md

File metadata and controls

345 lines (252 loc) · 7.4 KB

Contributing to LMP (Lattice Mesh Protocol)

Thank you for your interest in contributing to LMP! This document provides guidelines and instructions for contributing.

Table of Contents

Code of Conduct

This project adheres to a Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the maintainers.

Getting Started

Prerequisites

  • Rust 1.75+ - Install Rust
  • Git - For version control
  • A C compiler - Required for post-quantum crypto libraries (gcc/clang)

Project Structure

LMP_Lattice-Mesh-Protocol/
├── MAIN.md              # Protocol specification (read first!)
├── SECURITY.md          # Security details
├── GUIDE.md             # Developer guide
├── CONTRIBUTING.md      # This file
│
└── lmp-core/            # Core library
    ├── src/
    │   ├── crypto/      # Cryptographic primitives
    │   ├── protocol/    # Protocol logic
    │   ├── network/     # Mesh networking
    │   ├── storage/     # Persistence
    │   └── device/      # Identity management
    └── tests/           # Integration tests

How to Contribute

Ways to Contribute

  1. 🐛 Bug Reports - Found a bug? Open an issue!
  2. ✨ Feature Requests - Have an idea? We'd love to hear it!
  3. 📝 Documentation - Help improve our docs
  4. 🧪 Testing - Write tests, find edge cases
  5. 🔧 Code - Fix bugs, implement features
  6. 🔒 Security - Review crypto implementations

Good First Issues

Look for issues labeled:

  • good first issue - Great for newcomers
  • help wanted - We need assistance
  • documentation - Documentation improvements

Development Setup

1. Fork and Clone

# Fork the repository on GitHub, then:
git clone https://github.com/AaryanBansal-Dev/LMP_Lattice-Mesh-Protocol.git
cd LMP_Lattice-Mesh-Protocol

2. Build the Project

cd lmp-core
cargo build

3. Run Tests

# Run all tests
cargo test

# Run with verbose output
cargo test -- --nocapture

# Run a specific test
cargo test test_name

4. Check Code Quality

# Format code
cargo fmt

# Run linter
cargo clippy

# Check for security issues
cargo audit

5. Generate Documentation

cargo doc --open

Coding Standards

Rust Style

  • Follow Rust API Guidelines
  • Use cargo fmt before committing
  • Address all cargo clippy warnings
  • Write documentation for public APIs

Code Example

//! Module-level documentation explaining purpose.

use crate::error::{Error, Result};

/// Brief description of the function.
///
/// More detailed explanation if needed.
///
/// # Arguments
///
/// * `input` - Description of the input parameter
///
/// # Returns
///
/// Description of return value.
///
/// # Errors
///
/// * `Error::InvalidInput` - When input is invalid
///
/// # Example
///
/// ```rust
/// let result = my_function(input)?;
/// ```
pub fn my_function(input: &[u8]) -> Result<Vec<u8>> {
    if input.is_empty() {
        return Err(Error::InvalidInput("Input cannot be empty".into()));
    }
    
    // Implementation
    Ok(input.to_vec())
}

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

    #[test]
    fn test_my_function_success() {
        let result = my_function(b"test").unwrap();
        assert_eq!(result, b"test");
    }

    #[test]
    fn test_my_function_empty_input() {
        let result = my_function(b"");
        assert!(result.is_err());
    }
}

Security-Critical Code

For cryptographic code:

  1. Use constant-time operations for comparisons
  2. Zeroize secrets when they go out of scope
  3. Avoid branching on secrets (timing attacks)
  4. Document security assumptions
  5. Add security-focused tests
use zeroize::{Zeroize, ZeroizeOnDrop};

#[derive(Zeroize, ZeroizeOnDrop)]
struct SecretKey {
    bytes: [u8; 32],
}

// Use constant-time comparison
use crate::storage::memory::constant_time_eq;
if constant_time_eq(&received, &expected) {
    // OK
}

Commit Guidelines

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Types

Type Description
feat New feature
fix Bug fix
docs Documentation only
style Formatting, no code change
refactor Code refactoring
test Adding tests
chore Maintenance tasks
security Security improvements

Examples

feat(crypto): add Kyber768 key encapsulation

Implements the NIST-standardized Kyber768 post-quantum KEM.
Includes encapsulate and decapsulate functions with proper
error handling.

Closes #123

fix(ratchet): prevent nonce reuse in edge case

When message counter overflows, the nonce could potentially
be reused. Added check to trigger ratchet step before overflow.

Security: Prevents potential nonce reuse attack

docs(guide): add section on key rotation

Added detailed explanation of when and how different key types
are rotated, including code examples.

Pull Request Process

Before Opening a PR

  1. ✅ Read the docs - Understand the codebase
  2. ✅ Create an issue first - For significant changes
  3. ✅ Branch from main - Create a feature branch
  4. ✅ Keep changes focused - One feature/fix per PR
  5. ✅ Write tests - Cover new functionality
  6. ✅ Update docs - If behavior changes

PR Checklist

  • Code compiles without warnings (cargo build)
  • All tests pass (cargo test)
  • Code is formatted (cargo fmt)
  • Clippy is happy (cargo clippy)
  • Documentation updated if needed
  • Commit messages follow guidelines
  • PR description explains changes

Review Process

  1. Automated checks - CI runs tests
  2. Code review - Maintainer reviews code
  3. Discussion - Address feedback
  4. Approval - Maintainer approves
  5. Merge - Squash and merge

After Merge

  • Delete your feature branch
  • Update your fork's main branch
  • Celebrate! 🎉

Security Vulnerabilities

⚠️ Do NOT Open Public Issues for Security Bugs

If you discover a security vulnerability:

  1. Do NOT open a public issue
  2. Email the maintainers privately
  3. Include:
    • Description of the vulnerability
    • Steps to reproduce
    • Potential impact
    • Suggested fix (if any)

We will:

  • Acknowledge receipt within 48 hours
  • Provide a timeline for the fix
  • Credit you in the security advisory (if desired)

See SECURITY.md for our security policy.

Questions?

  • 📖 Check the Developer Guide
  • 💬 Open a Discussion on GitHub
  • 📧 Email the maintainers

Recognition

Contributors will be:

  • Listed in the project's contributors
  • Credited in release notes
  • Thanked in our community

Thank you for contributing to LMP! Together we're building a more private future. 🔐