Linux-Hello/CONTRIBUTING.md

Contributing to Linux Hello

Thank you for your interest in contributing to Linux Hello! This document provides guidelines and information for contributors.

Code of Conduct

We follow the Contributor Covenant. Please read it before participating.

Getting Started

Prerequisites

• Rust 1.70+ (install via rustup)
• GCC (for PAM module)
• Development packages:

  # Ubuntu/Debian
  sudo apt install build-essential libpam0g-dev v4l-utils pkg-config libssl-dev
  
  # Fedora
  sudo dnf install gcc make pam-devel v4l-utils pkgconfig openssl-devel
  
  # Arch Linux
  sudo pacman -S base-devel pam v4l-utils pkgconf openssl
  

Building

# Clone the repository
git clone https://github.com/YOUR_USERNAME/linux-hello.git
cd linux-hello

# Build all crates
cargo build

# Run tests
cargo test

# Build PAM module
cd pam-module && make

How to Contribute

Reporting Bugs

1. Check existing issues to avoid duplicates
2. Use the bug report template
3. Include:
   • Linux distribution and version
   • Camera hardware (if relevant)
   • Steps to reproduce
   • Expected vs actual behavior
   • Logs (if applicable)

Suggesting Features

1. Open an issue with the feature request template
2. Describe the use case
3. Explain how it benefits users

Code Contributions

1. Fork the repository
2. Create a branch from main:

   git checkout -b feature/your-feature-name
   

3. Make changes following our code style
4. Write/update tests for your changes
5. Run checks:

   cargo fmt --check
   cargo clippy
   cargo test
   

6. Commit with a clear message:

   git commit -m "feat: add new feature description"
   

7. Push and open a Pull Request

Commit Message Format

We follow Conventional Commits:

• feat: New feature
• fix: Bug fix
• docs: Documentation only
• style: Code style (formatting, etc.)
• refactor: Code refactoring
• test: Adding/updating tests
• chore: Maintenance tasks

Examples:

feat: add blink detection to anti-spoofing
fix: correct camera enumeration on Fedora
docs: update installation instructions for Arch

Code Style

Rust

• Follow rustfmt defaults
• Use cargo clippy to catch common issues
• Document public APIs with doc comments
• Keep functions under 60 lines when practical

/// Brief description of what the function does.
///
/// # Arguments
///
/// * `param` - Description of the parameter
///
/// # Returns
///
/// Description of return value
///
/// # Errors
///
/// When the function can fail and why
pub fn example_function(param: &str) -> Result<()> {
    // Implementation
}

C (PAM Module)

• Follow Linux kernel style
• No goto statements
• All loops must have fixed bounds
• Check all return values
• See CODING_STANDARDS.md for details

Testing

Running Tests

# All tests
cargo test

# Specific crate
cargo test -p linux-hello-daemon

# With output
cargo test -- --nocapture

# Integration tests (may require camera)
cargo test --test '*'

Writing Tests

• Place unit tests in the same file as the code
• Place integration tests in /tests/
• Use descriptive test names: test_function_condition_expected_result

Documentation

• Update README.md for user-facing changes
• Update docs/API.md for API changes
• Add inline documentation for complex code
• Include examples where helpful

Pull Request Process

1. Ensure all CI checks pass
2. Update documentation if needed
3. Add tests for new functionality
4. Request review from maintainers
5. Address review feedback
6. Squash commits if requested

Review Criteria

• Code quality and style
• Test coverage
• Documentation
• Security implications
• Performance impact

Security

If you discover a security vulnerability, please see SECURITY.md for responsible disclosure guidelines. Do not open public issues for security vulnerabilities.

License

By contributing, you agree that your contributions will be licensed under the GPL-3.0 License.

Questions?

• Open a Discussion for general questions
• Check existing issues and documentation first
• Be patient - maintainers are volunteers

Thank you for contributing! 🎉