chromebook-volume-buttons/CONTRIBUTING.md

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:

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

# 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:

sudo gpioinfo

2. Look for volume button GPIO lines

3. Update constants in volume_buttons.py:

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.