# Contributing to Irene Cipher

Thank you for your interest in contributing to Irene Cipher! This document provides guidelines for contributing to the project.

## Code of Conduct

- Be respectful and inclusive
- Welcome newcomers and help them learn
- Focus on constructive feedback
- Maintain a professional environment

## How to Contribute

### Reporting Bugs

1. Check if the bug has already been reported in [Issues](https://github.com/yourusername/irene-cipher/issues)
2. If not, create a new issue with:
   - Clear title and description
   - Steps to reproduce
   - Expected vs actual behavior
   - System information (OS, Python version, package version)
   - Code samples if applicable

### Suggesting Features

1. Check [Issues](https://github.com/yourusername/irene-cipher/issues) for existing suggestions
2. Create a new issue with:
   - Clear use case description
   - Why it's needed
   - Proposed API or implementation (optional)
   - Any security implications

### Pull Requests

1. **Fork and clone** the repository
2. **Create a branch** for your changes
3. **Make your changes** following our guidelines
4. **Test thoroughly** (see Testing section)
5. **Commit** with clear messages
6. **Push** to your fork
7. **Submit a PR** with description

## Development Setup

```bash
# Clone repository
git clone https://github.com/yourusername/irene-cipher.git
cd irene-cipher

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install maturin
pip install maturin

# Build in development mode
maturin develop

# Run tests
cargo test
python test_irene_cipher.py
```

## Coding Standards

### Rust Code

- Follow [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
- Run `cargo fmt` before committing
- Run `cargo clippy` and fix all warnings
- Add doc comments (`///`) for public items
- Write tests for new functionality
- Keep functions focused and small

Example:

```rust
/// Encrypts plaintext using password-based encryption
/// 
/// # Arguments
/// 
/// * `plaintext` - Data to encrypt
/// * `password` - Password for key derivation
/// 
/// # Returns
/// 
/// Encrypted bytes with salt and nonce prepended
pub fn encrypt(plaintext: &[u8], password: &str) -> Result<Vec<u8>> {
    // Implementation
}
```

### Python Code

- Follow [PEP 8](https://pep8.org/)
- Add docstrings for all functions
- Include type hints where applicable
- Write clear, readable code

### Commit Messages

Use clear, descriptive commit messages:

```
Add file streaming encryption support

- Implement chunked encryption for large files
- Add tests for multi-GB file handling
- Update documentation with streaming examples
```

Format:
- First line: Brief summary (50 chars or less)
- Blank line
- Detailed description if needed
- Reference issues: `Fixes #123`

## Testing

### Rust Tests

```bash
# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test test_name

# Run with coverage
cargo tarpaulin
```

### Python Tests

```bash
# Build first
maturin develop --release

# Run tests
python test_irene_cipher.py

# Run examples
python examples.py
```

### Test Requirements

- Add tests for all new features
- Ensure existing tests pass
- Test edge cases (empty input, large data, etc.)
- Test error conditions
- Aim for high code coverage

## Security Considerations

**CRITICAL**: This is a cryptographic library. Security is paramount.

### Security Guidelines

1. **Never invent cryptography**
   - Use established, audited algorithms
   - Don't create custom crypto schemes
   - When in doubt, ask for review

2. **Follow security best practices**
   - Use constant-time comparisons
   - Zero sensitive data after use
   - Avoid unsafe code in crypto operations
   - Handle errors securely

3. **Review carefully**
   - All crypto code requires thorough review
   - Security-critical changes need multiple reviewers
   - Consider edge cases and attack vectors

4. **Test security properties**
   - Test authentication failures
   - Test with tampered data
   - Test nonce uniqueness
   - Test key derivation

### What Requires Extra Scrutiny

- Changes to cryptographic algorithms
- Changes to key derivation
- Changes to nonce generation
- Changes to authentication
- Anything involving `unsafe` code
- Dependency updates (especially crypto crates)

## Documentation

### Required Documentation

- **Rust**: Doc comments for all public items
- **Python**: Docstrings for all functions
- **README**: Update if API changes
- **CHANGELOG**: Add entry for all changes
- **Examples**: Add if new feature is significant

### Documentation Style

- Clear and concise
- Include examples
- Explain security implications
- Warn about potential misuse
- Link to relevant specifications/RFCs

## Review Process

1. **Automated checks** must pass (CI/CD)
2. **Code review** by maintainer(s)
3. **Security review** for crypto changes
4. **Testing** verified by reviewer
5. **Documentation** reviewed
6. **Approval** and merge

## Release Process

1. Update version in `Cargo.toml` and `pyproject.toml`
2. Update `CHANGELOG.md`
3. Create git tag: `git tag v0.x.0`
4. Push tag: `git push origin v0.x.0`
5. GitHub Actions builds and publishes to PyPI

## Questions?

- Open a [Discussion](https://github.com/yourusername/irene-cipher/discussions)
- Ask in an [Issue](https://github.com/yourusername/irene-cipher/issues)
- Email maintainers (see README)

## License

By contributing, you agree that your contributions will be licensed under the MIT License.

---

**Thank you for contributing to Irene Cipher!**
