# Contributing to veilid-share
Thank you for interest in contributing to veilid-share! This document provides guidelines and instructions for contributing.
## Code of Conduct
Be respectful and constructive in all interactions.
## Getting Started
1. **Fork the repository** on GitHub
2. **Clone your fork** locally:
```bash
git clone git@github.com:danzbyrd/vflight.git
cd veilid-share
```
3. **Create a branch** for your work:
```bash
git checkout -b feature/your-feature-name
```
## Development Setup
```bash
# Build the project
cargo build
# Run tests
cargo test
# Run with logging
RUST_LOG=debug cargo run -- seed ./test_data/testfile.txt
```
## Code Quality Requirements
All pull requests must pass:
1. **Tests** - Add tests for new functionality:
```bash
cargo test
```
2. **Formatting** - Code must be formatted with rustfmt:
```bash
cargo fmt
```
3. **Linting** - No clippy warnings:
```bash
cargo clippy -- -D warnings
```
4. **Documentation** - Public items must have doc comments:
```bash
cargo doc --no-deps --open
```
## Commit Messages
Follow conventional commit format:
- `feat: add new feature`
- `fix: fix a bug`
- `docs: documentation updates`
- `test: add or modify tests`
- `refactor: code refactoring`
- `chore: build, dependencies, etc`
Example:
```
feat: add parallel chunk downloads for faster retrieval
- Implement concurrent chunk fetching with tokio
- Add bandwidth throttling
- Update tests and documentation
```
## Pull Request Process
1. **Update** your branch with latest main:
```bash
git fetch origin
git rebase origin/main
```
2. **Push** to your fork and create a PR on GitHub
3. **CI must pass** - All GitHub Actions workflows must succeed
4. **Request review** from maintainers
## Testing Guidelines
- Aim for >80% code coverage on new code
- Test both success and error cases
- Use `tempfile` crate for file-based tests
- Examples:
```rust
#[test]
fn test_chunk_file_multiple_chunks() {
let temp_dir = TempDir::new().unwrap();
let test_file = temp_dir.path().join("large.bin");
let test_data = vec![42u8; CHUNK_SIZE * 3 + 1000];
fs::write(&test_file, &test_data).unwrap();
let chunks = chunk_file(&test_file).unwrap();
assert_eq!(chunks.len(), 4);
}
```
## Performance Considerations
- Chunk size is 30KB - changes should be justified
- Use async/await for network operations
- Profile before and after performance changes
- Document any performance trade-offs
## Documentation Standards
- All public items require doc comments
- Include examples for complex functions
- Keep README.md up-to-date with features
- Add to CHANGELOG.md when appropriate
````rust
/// Brief description
///
/// Longer description if needed
///
/// # Arguments
/// * `param` - description
///
/// # Returns
/// Description of return value
///
/// # Example
/// ```
/// let result = function(args)?;
/// ```
pub fn function(param: Type) -> Result<ReturnType> {
// ...
}
````
## Issues
- Check existing issues before opening new ones
- Use clear, descriptive titles
- Include reproduction steps for bugs
- Provide context and environment info
## Questions?
Open a GitHub Discussion or issue with your question.
## License
By contributing, you agree your code is licensed under the MIT License.
Thank you for contributing! 🎉