# Contributing to Instafy
Thank you for your interest in contributing to Instafy! This document provides guidelines and instructions for contributing.
## Code of Conduct
Be respectful and inclusive. We're all here to make this project better.
## Getting Started
1. **Fork the repository** on GitHub
2. **Clone your fork** locally:
```bash
git clone https://github.com/yourusername/instafy.git
cd instafy
```
3. **Add upstream remote**:
```bash
git remote add upstream https://github.com/originalowner/instafy.git
```
## Development Setup
### Prerequisites
- Rust 1.70 or later
- Cargo
- cargo-nextest (optional but recommended)
### Install Dependencies
```bash
cargo build
```
### Install cargo-nextest (recommended)
```bash
cargo install cargo-nextest
```
## Development Workflow
### 1. Create a Feature Branch
```bash
git checkout -b feature/your-feature-name
```
Use descriptive branch names:
- `feature/` for new features
- `fix/` for bug fixes
- `docs/` for documentation changes
- `refactor/` for code refactoring
### 2. Make Your Changes
- Write clean, idiomatic Rust code
- Follow existing code style and conventions
- Add tests for new functionality
- Update documentation as needed
### 3. Test Your Changes
Run the full test suite:
```bash
cargo nextest run
```
Or with standard cargo:
```bash
cargo test
```
Check for warnings:
```bash
cargo clippy
```
Format your code:
```bash
cargo fmt
```
### 4. Commit Your Changes
Write clear, descriptive commit messages:
```bash
git commit -m "feat: add support for PNG output format"
```
Use conventional commit prefixes:
- `feat:` - New feature
- `fix:` - Bug fix
- `docs:` - Documentation changes
- `test:` - Adding or updating tests
- `refactor:` - Code refactoring
- `perf:` - Performance improvements
- `chore:` - Maintenance tasks
### 5. Push and Create Pull Request
```bash
git push origin feature/your-feature-name
```
Then create a Pull Request on GitHub.
## Pull Request Guidelines
### Before Submitting
- [ ] All tests pass (`cargo nextest run`)
- [ ] No compiler warnings (`cargo build`)
- [ ] Code is formatted (`cargo fmt`)
- [ ] Clippy checks pass (`cargo clippy`)
- [ ] Documentation is updated if needed
- [ ] CHANGELOG.md is updated (if applicable)
### PR Description
Include in your PR description:
1. **What** - What changes are you making?
2. **Why** - Why are these changes needed?
3. **How** - How do these changes work?
4. **Testing** - How did you test these changes?
### Example PR Template
```markdown
## Description
Brief description of changes
## Motivation
Why are these changes needed?
## Changes
- Change 1
- Change 2
## Testing
- [ ] Unit tests added/updated
- [ ] Manual testing performed
- [ ] All tests pass
## Screenshots (if applicable)
Add screenshots for UI changes
```
## Testing Guidelines
### Test-Driven Development
We follow TDD practices:
1. Write tests first (red)
2. Implement functionality (green)
3. Refactor (refactor)
### Test Structure
```rust
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_descriptive_name() {
// Arrange
let input = create_test_data();
// Act
let result = function_under_test(input);
// Assert
assert_eq!(result, expected_value);
}
}
```
### What to Test
- All public functions
- Edge cases (empty inputs, boundary values)
- Error conditions
- Integration between components
## Code Style
### Rust Style Guide
Follow the [Rust Style Guide](https://doc.rust-lang.org/1.0.0/style/):
- Use `snake_case` for functions and variables
- Use `PascalCase` for types and traits
- Use `SCREAMING_SNAKE_CASE` for constants
- Prefer explicit over implicit
- Use meaningful variable names
### Comments and Documentation
- Document all public APIs with `///` doc comments
- Include examples in documentation
- Use `//` for inline comments explaining complex logic
- Keep comments up-to-date with code changes
Example:
```rust
/// Creates a composite image with blurred background and sharp foreground
///
/// # Arguments
///
/// * `original` - The source image to process
/// * `target_size` - Output image dimensions (width and height)
/// * `blur_sigma` - Blur intensity (higher = more blur)
///
/// # Returns
///
/// Returns a new `RgbaImage` with the composite result
///
/// # Examples
///
/// ```
/// use instafy::create_composite_image;
///
/// let img = image::open("photo.jpg")?;
/// let result = create_composite_image(&img, 1080, 20.0)?;
/// ```
pub fn create_composite_image(
original: &DynamicImage,
target_size: u32,
blur_sigma: f32,
) -> Result<RgbaImage> {
// Implementation
}
```
## Logging Guidelines
Use appropriate log levels:
- `error!()` - For errors that prevent operation
- `warn!()` - For recoverable issues
- `info!()` - For important state changes
- `debug!()` - For detailed debugging information
- `trace!()` - For very verbose output
Use `#[instrument]` for function tracing:
```rust
#[instrument(skip(large_param))]
fn process_data(large_param: &Data) -> Result<()> {
debug!("Processing started");
// Implementation
}
```
## Adding New Features
### Feature Checklist
- [ ] Design the feature (consider API, performance, maintainability)
- [ ] Write tests (TDD approach)
- [ ] Implement the feature
- [ ] Add documentation
- [ ] Update README.md with usage examples
- [ ] Update CHANGELOG.md
- [ ] Test edge cases
- [ ] Run full test suite
- [ ] Create pull request
### Breaking Changes
If your change is breaking:
1. Discuss it in an issue first
2. Update major version number
3. Document migration path in CHANGELOG.md
4. Update all examples and documentation
## Documentation
### README Updates
Update README.md when:
- Adding new features
- Changing CLI options
- Adding new dependencies
- Changing build process
### Code Documentation
- Document all public APIs
- Include examples in docs
- Use `cargo doc --open` to preview
### CHANGELOG Updates
Follow [Keep a Changelog](https://keepachangelog.com/) format:
```markdown
## [Unreleased]
### Added
- New feature X
### Changed
- Modified behavior Y
### Fixed
- Bug Z
```
## Issue Reporting
### Bug Reports
Include:
- Instafy version
- Operating system
- Rust version
- Steps to reproduce
- Expected behavior
- Actual behavior
- Sample images (if applicable)
### Feature Requests
Include:
- Use case description
- Proposed solution
- Alternative solutions considered
- Example usage
## Getting Help
- Check existing issues and discussions
- Read the documentation
- Ask questions in issues (use `question` label)
## Recognition
Contributors will be:
- Listed in CHANGELOG.md for their contributions
- Credited in release notes
- Acknowledged in the project
Thank you for contributing to Instafy! 🎉