# 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](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
Please read it before participating.

## Getting Started

### Prerequisites

- Rust 1.70+ (install via [rustup](https://rustup.rs/))
- GCC (for PAM module)
- Development packages:
  ```bash
  # 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

```bash
# 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](../../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`:
   ```bash
   git checkout -b feature/your-feature-name
   ```
3. **Make changes** following our code style
4. **Write/update tests** for your changes
5. **Run checks**:
   ```bash
   cargo fmt --check
   cargo clippy
   cargo test
   ```
6. **Commit** with a clear message:
   ```bash
   git commit -m "feat: add new feature description"
   ```
7. **Push** and open a Pull Request

### Commit Message Format

We follow [Conventional Commits](https://www.conventionalcommits.org/):

- `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

```rust
/// 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](CODING_STANDARDS.md) for details

## Testing

### Running Tests

```bash
# 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](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](LICENSE).

## Questions?

- Open a [Discussion](../../discussions) for general questions
- Check existing issues and documentation first
- Be patient - maintainers are volunteers

Thank you for contributing! 🎉