# Contributing to Chromebook Volume Buttons Driver

Thank you for considering contributing to this project. This document provides guidelines for contributions.

## Code of Conduct

- Be respectful and constructive
- Focus on technical merit
- Help maintain a welcoming environment

## How to Contribute

### Reporting Bugs

When reporting bugs, please include:

1. **Hardware Information:**
   - Chromebook model and codename
   - Processor model
   - BIOS version
   - Linux kernel version

2. **Software Environment:**
   - Python version
   - libgpiod version
   - python-evdev version

3. **Issue Description:**
   - Expected behavior
   - Actual behavior
   - Steps to reproduce
   - Relevant log output

4. **GPIO Information:**
```bash
sudo gpioinfo | grep -E "VOLDN|VOLUP"
```

### Suggesting Enhancements

Enhancement suggestions should include:
- Clear description of the feature
- Use case and motivation
- Implementation considerations
- Potential impact on existing functionality

### Pull Requests

1. **Before Starting:**
   - Check existing issues and pull requests
   - Discuss major changes in an issue first
   - Ensure you have test hardware available

2. **Code Standards:**
   - Follow PEP 8 style guide
   - Use meaningful variable and function names
   - Add docstrings for functions and classes
   - Keep lines under 100 characters where practical

3. **Commit Guidelines:**
   - Write clear, descriptive commit messages
   - Use present tense ("Add feature" not "Added feature")
   - Reference issues when applicable
   - Keep commits focused and atomic

4. **Testing:**
   - Test on actual hardware
   - Verify service starts/stops correctly
   - Check for resource leaks during extended operation
   - Ensure CPU usage remains low

5. **Documentation:**
   - Update README.md for feature changes
   - Update CHANGELOG.md following Keep a Changelog format
   - Add inline comments for complex logic
   - Update hardware compatibility list if applicable

### Development Setup

```bash
# Clone repository
git clone https://gitea.legion-muyue.fr/Muyue/chromebook-volume-buttons.git
cd chromebook-volume-buttons

# Install dependencies
sudo pacman -S python-evdev libgpiod

# Test script directly
sudo python3 volume_buttons.py
```

### GPIO Mapping for New Hardware

If porting to different Chromebook models:

1. Identify GPIO chip and pins:
```bash
sudo gpioinfo
```

2. Look for volume button GPIO lines

3. Update constants in `volume_buttons.py`:
```python
CHIP_PATH = "/dev/gpiochipX"  # Update chip number
VOLUME_DOWN_PIN = X           # Update pin number
VOLUME_UP_PIN = Y             # Update pin number
```

4. Test and document hardware in README.md

### Code Review Process

1. Maintainer reviews code for:
   - Correctness
   - Style compliance
   - Documentation completeness
   - Hardware compatibility impact

2. Changes may be requested before merge

3. Once approved, changes are merged to main branch

### Release Process

1. Version numbers follow Semantic Versioning
2. CHANGELOG.md updated with all changes
3. Git tag created for release
4. Release notes generated from CHANGELOG.md

## Questions

For questions about contributing, open an issue with the "question" label.

## License

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