# Contributing to LCPFS
Thank you for your interest in contributing to LCPFS! This document provides
guidelines and instructions for contributing.
## Code of Conduct
By participating in this project, you agree to maintain a respectful and
inclusive environment. Be kind, constructive, and professional in all
interactions.
## Getting Started
### Prerequisites
- Rust nightly toolchain (2024 edition)
- Git
### Setting Up Development Environment
```bash
# Clone the repository
git clone https://github.com/artst3in/lcpfs.git
cd lcpfs
# Install Rust nightly
rustup default nightly
# Build the project
cargo build
# Run tests
cargo test
# Run tests with all features
cargo test --all-features
```
## How to Contribute
### Reporting Bugs
1. Check existing issues to avoid duplicates
2. Use the bug report template
3. Include:
- Rust version (`rustc --version`)
- Operating system
- Minimal reproduction case
- Expected vs actual behavior
- Full error output
### Suggesting Features
1. Check existing issues and discussions
2. Open a discussion before creating a PR for major features
3. Describe the use case and motivation
4. Consider backwards compatibility
### Submitting Pull Requests
1. Fork the repository
2. Create a feature branch from `main`:
```bash
git checkout -b feature/your-feature-name
```
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass:
```bash
cargo test --all-features
```
6. Run clippy and fix warnings:
```bash
cargo clippy --all-features -- -D warnings
```
7. Format code:
```bash
cargo fmt
```
8. Write clear commit messages
9. Push and open a PR against `main`
## Coding Standards
### Style
- Follow Rust standard conventions
- Use `cargo fmt` for formatting
- Use `cargo clippy` for linting
- Keep lines under 100 characters when practical
### Documentation
- Document all public APIs with doc comments
- Include examples in doc comments where helpful
- Update README.md for user-facing changes
- Update CHANGELOG.md following Keep a Changelog format
### Testing
- Write unit tests for new functionality
- Write integration tests for complex features
- Maintain or improve code coverage
- Test both `std` and `no_std` configurations:
```bash
cargo test
cargo test --no-default-features
```
### Commit Messages
Follow conventional commits format:
```
type(scope): brief description
Longer explanation if needed.
Fixes #123
```
Types:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
- `style`: Formatting, no code change
- `refactor`: Code change without feature/fix
- `perf`: Performance improvement
- `test`: Adding tests
- `chore`: Maintenance tasks
### no_std Compatibility
LCPFS supports `no_std` environments. When contributing:
- Avoid `std`-only APIs in core modules
- Gate `std`-specific code with `#[cfg(feature = "std")]`
- Use `alloc` crate for heap allocation
- Test with `--no-default-features`
## Architecture Guidelines
### Module Organization
```
src/
├── lib.rs # Public API, re-exports
├── arc.rs # Adaptive Replacement Cache
├── vdev.rs # Virtual device abstraction
├── spa.rs # Storage Pool Allocator
├── dmu.rs # Data Management Unit
├── zpl.rs # ZFS POSIX Layer
├── zil.rs # Intent Log
├── checksum.rs # Checksumming
├── compress.rs # Compression
├── dedup.rs # Deduplication
└── ...
```
### Design Principles
1. **Copy-on-Write**: Never modify data in place
2. **Checksums Everywhere**: All data must be checksummed
3. **Transactional**: Operations are atomic
4. **no_std First**: Core functionality works without std
### Error Handling
- Use `FsError` for filesystem errors
- Provide context in error messages
- Don't panic in library code
- Use `Result` for fallible operations
## Review Process
1. PRs require at least one approval
2. CI must pass (tests, clippy, fmt)
3. Documentation must be updated
4. CHANGELOG must be updated for user-facing changes
## License
By contributing, you agree that your contributions will be licensed under
the Apache License 2.0.
## Questions?
- Open a GitHub Discussion for general questions
- Open an Issue for bugs or feature requests
- See README.md for usage documentation
Thank you for contributing to LCPFS!