# Contributing to tui-slider

Thank you for your interest in contributing to tui-slider! This document provides guidelines and instructions for contributing.

## Code of Conduct

Be respectful, inclusive, and constructive in all interactions.

## How to Contribute

### Reporting Bugs

Before creating a bug report:
- Check the issue tracker to avoid duplicates
- Collect relevant information (OS, terminal, Rust version)
- Create a minimal reproducible example if possible

When filing a bug report, include:
- Clear description of the issue
- Steps to reproduce
- Expected vs actual behavior
- Environment details
- Code samples or screenshots

### Suggesting Features

For feature requests:
- Check existing issues and discussions
- Clearly describe the use case
- Provide examples of how it would work
- Consider backwards compatibility

### Pull Requests

All contributions must be submitted through GitHub using the forking workflow:

1. **Fork the Repository**
   - Visit https://github.com/sorinirimies/tui-slider
   - Click the "Fork" button to create your own copy of the repository

2. **Clone Your Fork**
   ```bash
   git clone https://github.com/YOUR-USERNAME/tui-slider.git
   cd tui-slider
   ```

3. **Add Upstream Remote**
   ```bash
   git remote add upstream https://github.com/sorinirimies/tui-slider.git
   ```

4. **Create a Branch**
   ```bash
   git checkout -b feature/my-new-feature
   ```

5. **Make Changes**
   - Write clear, idiomatic Rust code
   - Follow existing code style
   - Add tests for new functionality
   - Update documentation as needed

6. **Run Tests**
   ```bash
   cargo test
   cargo clippy -- -D warnings
   cargo fmt --check
   ```

7. **Commit Changes**
   - Use conventional commit messages
   - Examples: `feat: add gradient color support`, `fix: handle edge case in animation`

8. **Push to Your Fork**
   ```bash
   git push origin feature/my-new-feature
   ```

9. **Create Pull Request**
   - Go to your fork on GitHub
   - Click "Compare & pull request"
   - Fill in the PR description with details about your changes
   - Submit the PR to the main repository

**Note**: Do not submit patches or contributions through email or other channels. All contributions must go through GitHub's pull request system on your forked repository.

## Development Setup

### Prerequisites

- Rust 1.74.0 or later
- A terminal that supports Unicode (for full visual testing)

### Building

```bash
# Build the library
cargo build

# Build with all features
cargo build --all-features

# Build examples
cargo build --examples
```

### Testing

```bash
# Run all tests
cargo test

# Run specific test
cargo test test_name

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

### Running Examples

```bash
# Run specific example
cargo run --example horizontal

# Or use just
just example-horizontal
```

### Using Just

This project includes a `justfile` for common tasks:

```bash
# List all commands
just

# Run checks (format, clippy, test)
just check

# Format code
just fmt

# Run clippy
just clippy

# Build documentation
just doc
```

## Code Style

### Rust Style

- Follow the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
- Use `cargo fmt` for formatting
- Use `cargo clippy` to catch common mistakes
- Write idiomatic Rust code

### Documentation

- Add doc comments for all public items
- Include examples in doc comments
- Use `///` for item documentation
- Use `//!` for module documentation
- Run `cargo doc --open` to preview

Example:
```rust
/// Creates a new slider with the given value and bounds
///
/// # Arguments
///
/// * `value` - Initial value
/// * `min` - Minimum value
/// * `max` - Maximum value
///
/// # Example
///
/// ```
/// use tui_slider::Slider;
/// let slider = Slider::new(50.0, 0.0, 100.0);
/// ```
pub fn new(value: f64, min: f64, max: f64) -> Self {
    // ...
}
```

### Testing

- Write unit tests for new functionality
- Add integration tests where appropriate
- Test edge cases and error conditions
- Aim for good test coverage

Example:
```rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_slider_bounds() {
        let slider = Slider::new(150.0, 0.0, 100.0);
        assert_eq!(slider.value(), 100.0);
    }
}
```

## Project Structure

```
tui-slider/
├── src/
│   ├── lib.rs           # Main library entry point
│   ├── slider.rs        # Main slider widget
│   ├── state.rs         # State management
│   ├── orientation.rs   # Orientation types
│   ├── symbols.rs       # Symbol sets
│   ├── styles.rs        # Visual styles
│   ├── colors.rs        # Color gradients
│   └── animation.rs     # Animation system
├── examples/            # Example applications
├── tests/               # Integration tests
└── benches/             # Benchmarks (future)
```

## Adding New Features

### New Slider Style

1. Add the style definition in `src/styles.rs`
2. Create a preset method (e.g., `pub fn my_style()`)
3. Add tests for the new style
4. Document with examples
5. Consider adding an example in `examples/`

### New Symbol Set

1. Add symbols in `src/symbols.rs`
2. Create preset methods for handle and bar
3. Add to the `SliderSymbols` presets
4. Test the symbols render correctly
5. Update documentation

### New Animation Easing

1. Add the easing variant to `AnimationEasing` enum in `src/animation.rs`
2. Implement the easing function in the `apply()` method
3. Add tests for the easing function
4. Document the easing behavior

## Examples

When adding examples:
- Place in `examples/` directory
- Include clear comments explaining functionality
- Add keyboard controls help text
- Register in `Cargo.toml` under `[[example]]`
- Update README with description and run command

## Documentation

### README Updates

When adding significant features:
- Update feature list
- Add examples showing usage
- Update API sections
- Add to appropriate sections

### CHANGELOG

Follow [Keep a Changelog](https://keepachangelog.com/):
- Add entries under `[Unreleased]`
- Use categories: Added, Changed, Deprecated, Removed, Fixed, Security
- Write clear, user-focused descriptions

## Release Process

Maintainers only:

1. Update version in `Cargo.toml`
2. Update `CHANGELOG.md`
3. Create git tag: `git tag -a v0.x.x -m "Release v0.x.x"`
4. Push tag: `git push origin v0.x.x`
5. CI will build and publish to crates.io

## Questions?

- Open an issue for questions
- Check existing documentation
- Review examples for usage patterns

## License

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

---

Thank you for contributing to tui-slider! 🎚️