clock-hash 1.0.0

# Contributing to ClockHash-256

Thank you for your interest in contributing to ClockHash-256! This document provides guidelines and information for contributors.

## 🚀 Quick Start

### Prerequisites

- **Rust**: Install Rust 1.85.0 or later ([rustup.rs](https://rustup.rs))
- **Git**: Version control system
- **Optional**: For fuzzing - nightly Rust toolchain

### Development Setup

1. **Fork and Clone**:
   ```bash
   git clone https://github.com/YOUR_USERNAME/clock-hash.git
   cd clock-hash
   ```

2. **Add upstream remote**:
   ```bash
   git remote add upstream https://github.com/clockinchain/clock-hash.git
   ```

3. **Install dependencies** (if any):
   ```bash
   cargo build
   ```

4. **Run tests**:
   ```bash
   cargo test
   ```

## 📝 Development Workflow

### 1. Choose an Issue

- Check [GitHub Issues](https://github.com/clockinchain/clock-hash/issues) for open tasks
- Look for issues labeled `good first issue` or `help wanted`
- Comment on the issue to indicate you're working on it

### 2. Create a Branch

```bash
git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-number-description
```

### 3. Make Changes

- Follow the [code style guidelines](#code-style)
- Add tests for new functionality
- Update documentation as needed
- Ensure all tests pass: `cargo test`

### 4. Commit Changes

- Write clear, descriptive commit messages
- Follow conventional commit format when possible
- Keep commits focused on single changes

```bash
git add .
git commit -m "feat: add new feature description"
```

### 5. Push and Create Pull Request

```bash
git push origin your-branch-name
```

Then create a Pull Request on GitHub with:
- Clear title describing the change
- Detailed description of what was changed and why
- Reference to any related issues

## 🎨 Code Style

### Rust Formatting

We use `rustfmt` with the configuration in `rustfmt.toml`. The CI will check formatting:

```bash
# Check formatting
cargo fmt --check

# Apply formatting
cargo fmt
```

### Linting

We use `clippy` with strict settings. The CI will run linting checks:

```bash
# Check for lint issues
cargo clippy --all-targets --all-features -- -D warnings

# Fix auto-fixable issues
cargo clippy --fix
```

### Naming Conventions

- **Functions**: `snake_case`
- **Types/Structs**: `PascalCase`
- **Constants**: `SCREAMING_SNAKE_CASE`
- **Modules**: `snake_case`
- **Cryptographic functions**: Follow established naming patterns

### Documentation

- All public APIs must have documentation comments (`///`)
- Include code examples where helpful
- Document security implications of cryptographic functions
- Update README.md for significant changes

## 🧪 Testing

### Running Tests

```bash
# Run all tests
cargo test

# Run specific test
cargo test test_name

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

# Run tests for specific feature
cargo test --features no_std
```

### Test Coverage

- Maintain high test coverage (>90% target)
- Test both success and failure cases
- Include property-based tests for cryptographic properties
- Test edge cases and boundary conditions

### Fuzz Testing

```bash
# Install cargo-fuzz (nightly required)
cargo install cargo-fuzz

# Run fuzzing
cd fuzz
cargo fuzz run clockhash256_fuzz
```

## 🔒 Security Considerations

**⚠️ IMPORTANT**: ClockHash-256 is a cryptographic library. Security is paramount.

### Security Requirements

1. **No Breaking Changes to Cryptographic Behavior**: Any change affecting hash outputs requires careful review
2. **Constant-Time Operations**: Ensure all cryptographic operations are constant-time
3. **Side-Channel Resistance**: Avoid timing and cache-based side channels
4. **Memory Safety**: Leverage Rust's guarantees, avoid unsafe code when possible

### Security Review Process

1. **Self-Review**: Check for security implications before submitting
2. **Automated Checks**: All PRs run security audits via `cargo audit`
3. **Manual Review**: Security-sensitive changes require manual review
4. **Testing**: Comprehensive testing including property-based tests

### Reporting Security Issues

See [SECURITY.md](SECURITY.md) for vulnerability reporting procedures.

## 📋 Pull Request Process

### PR Checklist

- [ ] Tests pass: `cargo test`
- [ ] Code formatted: `cargo fmt --check`
- [ ] Lints pass: `cargo clippy -- -D warnings`
- [ ] Documentation updated
- [ ] CHANGELOG.md updated (if applicable)
- [ ] Commit messages are clear and descriptive

### PR Review Process

1. **Automated Checks**: CI must pass all checks
2. **Code Review**: At least one maintainer review required
3. **Security Review**: For cryptographic changes
4. **Testing**: Additional testing may be requested
5. **Approval**: Maintainers approve and merge

### PR Types

- **Features**: New functionality (prefix: `feat:`)
- **Bug Fixes**: Bug fixes (prefix: `fix:`)
- **Documentation**: Documentation changes (prefix: `docs:`)
- **Refactoring**: Code restructuring (prefix: `refactor:`)
- **Testing**: Test-related changes (prefix: `test:`)
- **CI/CD**: Build/tooling changes (prefix: `ci:`)

## 🔧 Development Tools

### Recommended Editor Setup

- **VS Code** with rust-analyzer extension
- **CLion** with Rust plugin
- Configure format-on-save and clippy integration

### Useful Commands

```bash
# Full CI check locally
cargo fmt --check && cargo clippy -- -D warnings && cargo test

# Security audit
cargo audit

# Benchmarks
cargo bench

# Documentation
cargo doc --open
```

## 📚 Learning Resources

- [The Rust Programming Language Book](https://doc.rust-lang.org/book/)
- [Rustonomicon](https://doc.rust-lang.org/nomicon/) (for unsafe code)
- [Cryptographic Best Practices](https://cryptography.io/)
- [ClockHash-256 RFC](docs/rfc-0002.md)

## 🤝 Code of Conduct

- Be respectful and inclusive
- Focus on constructive feedback
- Security issues go through proper channels (see SECURITY.md)
- Maintain professional communication

## 📞 Getting Help

- **Issues**: [GitHub Issues](https://github.com/clockinchain/clock-hash/issues)
- **Discussions**: [GitHub Discussions](https://github.com/clockinchain/clock-hash/discussions)
- **Documentation**: Check existing docs and RFC first

## 🙏 Recognition

Contributors are recognized in CHANGELOG.md and may be acknowledged in release notes. Significant contributions may be recognized in the project README.

---

Thank you for contributing to ClockHash-256! Your efforts help make blockchain technology more secure and efficient. 🚀