Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
246 lines (189 loc) · 5.75 KB

CONTRIBUTING.md

File metadata and controls

246 lines (189 loc) · 5.75 KB

Contributing to FrameLab

First off, thank you for considering contributing to FrameLab! It's people like you that make this tool better for the cycling community.

Code of Conduct

Be respectful, inclusive, and constructive. We're all here to make bike fitting more accessible.

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check existing issues. When you create a bug report, include as many details as possible:

  • Use a clear and descriptive title
  • Describe the exact steps to reproduce the problem
  • Provide specific examples
  • Describe the behavior you observed and what you expected
  • Include screenshots if applicable
  • Include your environment: OS, Python version, camera type

Bug Report Template:

## Description
[Clear description of the bug]

## Steps to Reproduce
1. Step 1
2. Step 2
3. ...

## Expected Behavior
[What you expected to happen]

## Actual Behavior
[What actually happened]

## Environment
- OS: [e.g., Windows 11, macOS 14.0, Ubuntu 22.04]
- Python Version: [e.g., 3.9.10]
- Camera: [e.g., Logitech C920]
- ANT+ Dongle: [if applicable]

## Screenshots
[If applicable]

## Additional Context
[Any other information]

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion:

  • Use a clear and descriptive title
  • Provide a detailed description of the suggested enhancement
  • Explain why this enhancement would be useful
  • List some examples of how it would be used

Pull Requests

  1. Fork the repo and create your branch from main
  2. Make your changes:
    • Follow the existing code style
    • Add comments for complex logic
    • Update documentation if needed
  3. Test your changes:
    • Test on your platform thoroughly
    • If possible, test on multiple platforms
    • Ensure existing functionality still works
  4. Commit your changes:
    • Use clear, descriptive commit messages
    • Reference issues if applicable
  5. Push to your fork and submit a pull request

Pull Request Template:

## Description
[Clear description of what this PR does]

## Related Issue
Fixes #[issue number]

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Testing
- [ ] Tested on Windows
- [ ] Tested on macOS
- [ ] Tested on Linux
- [ ] All existing features still work
- [ ] New features work as expected

## Screenshots
[If applicable]

## Checklist
- [ ] My code follows the project's code style
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have updated the documentation accordingly
- [ ] My changes generate no new warnings
- [ ] I have tested my changes thoroughly

Development Setup

Prerequisites

  • Python 3.8-3.12
  • Git
  • Camera (for testing)
  • Optional: ANT+ dongle (for trainer testing)

Setup Steps

  1. Clone your fork:
git clone https://github.com/YOUR-USERNAME/framelab.git
cd framelab
  1. Create a virtual environment:
python -m venv venv
source venv/bin/activate  # macOS/Linux
# OR
venv\Scripts\Activate.ps1  # Windows
  1. Install dependencies:
pip install -r requirements.txt
  1. Create a branch:
git checkout -b feature/your-feature-name

  1. Make your changes and test

  2. Commit and push:

git add .
git commit -m "Add your feature"
git push origin feature/your-feature-name
  1. Create a Pull Request on GitHub

Code Style Guidelines

Python Style

  • Follow PEP 8 guidelines
  • Use meaningful variable names
  • Keep functions focused and single-purpose
  • Maximum line length: 120 characters
  • Use type hints where appropriate

Comments

  • Comment complex logic
  • Use docstrings for functions and classes
  • Keep comments concise and clear

Example:

def calculate_saddle_height(hip_point, ankle_point):
    """
    Calculate saddle height from hip to ankle.
    
    Args:
        hip_point: Tuple of (x, y) coordinates for hip
        ankle_point: Tuple of (x, y) coordinates for ankle
    
    Returns:
        float: Vertical distance in pixels
    """
    return abs(hip_point[1] - ankle_point[1])

Project Areas

High Priority

  • Performance optimization
  • Cross-platform testing
  • Bug fixes
  • Documentation improvements

Feature Ideas

  • Additional measurement types
  • 3D visualization
  • ML-powered recommendations
  • Integration with training platforms
  • Mobile app support
  • Internationalization

Platform-Specific

  • Windows: PowerShell scripts, Visual C++ dependencies
  • macOS: Camera permissions, M1/M2 compatibility
  • Linux: udev rules for ANT+, various distributions

Testing

Before Submitting PR

  1. Test basic functionality:

    • Camera detection
    • Pose detection
    • Recording
    • Measurements (if calibrated)

  2. Test new features thoroughly

  3. Test on your platform (Windows/macOS/Linux)

  4. Check for regressions in existing features

Manual Testing Checklist

  • Application launches without errors
  • Camera is detected
  • Pose detection works
  • Angles calculated correctly
  • Recording works
  • Files save correctly
  • Settings persist
  • Session management works
  • Calibration works (if applicable)
  • Measurements accurate (if applicable)

Questions?

  • Open an issue for questions
  • Use GitHub Discussions for general discussion
  • Be patient - this is a community project

Recognition

Contributors will be:

  • Listed in the repository
  • Credited in release notes
  • Part of making bike fitting accessible to everyone

Thank you for contributing to FrameLab! 🚴‍♂️