gh-christianlouis-quizzicalbeats/docs/developer-guide/contributing.md

Contributing to Quizzical Beats

This guide provides information for developers who want to contribute to the Quizzical Beats project.

Getting Started

Development Environment Setup

1. Fork the repository on GitHub

2. Clone your fork locally:

   git clone https://github.com/YOUR-USERNAME/musicround.git
   cd musicround
   

3. Set up a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

4. Install development dependencies:

   pip install -r requirements-dev.txt
   

5. Set up pre-commit hooks:

   pre-commit install
   

6. Configure your environment variables for development:

   cp .env.example .env.dev
   # Edit .env.dev with your development settings
   

Development Workflow

Branching Strategy

We use a simplified Git flow approach:

• main: Production-ready code
• develop: Main development branch
• Feature branches: Created from develop for new features
• Bugfix branches: Created from develop for bug fixes
• Hotfix branches: Created from main for critical fixes

Naming conventions:

• Feature branches: feature/short-description
• Bug fix branches: bugfix/issue-number-description
• Hotfix branches: hotfix/issue-number-description

Making Changes

1. Create a new branch from develop:

   git checkout develop
   git pull origin develop
   git checkout -b feature/your-feature-name
   

2. Make your changes, following the coding standards

3. Run tests to ensure your changes don't break existing functionality:

   pytest
   

4. Commit your changes with a descriptive message:

   git commit -am "Add feature: short description
   
   More detailed explanation of the changes if needed.
   Fixes #123"
   

5. Push your branch to your fork:

   git push origin feature/your-feature-name
   

6. Create a pull request from your branch to the develop branch of the main repository

Coding Standards

Python Style Guide

We follow PEP 8 with some modifications:

• Line length: 100 characters maximum
• Use 4 spaces for indentation (no tabs)
• Use docstrings for all classes and functions
• Follow Google's Python Style Guide for docstrings

Flask-Specific Guidelines

• Organize routes by functionality in blueprints
• Keep view functions small and focused
• Use decorators for common patterns
• Prefer class-based views for complex endpoints

Testing Guidelines

• Write tests for all new features
• Maintain or improve test coverage
• Structure tests in a similar way to the code they test
• Use fixtures for common setup
• Mock external services in tests

Pull Request Process

1. Ensure your code passes all tests and linting checks
2. Update documentation if your changes affect it
3. Add your changes to the CHANGELOG.md under "Unreleased"
4. Request a review from at least one maintainer
5. Address any feedback from the reviewer
6. Once approved, a maintainer will merge your PR

Database Migrations

When making changes to the database schema:

1. Create a new migration script in the migrations/ directory
2. Name it descriptively (e.g., add_user_preferences.py)
3. Implement both upgrade and downgrade paths
4. Test the migration in both directions
5. Document the changes in the database schema documentation

Example migration script:

# migrations/add_user_preferences.py

def upgrade(db):
    db.execute("""
    ALTER TABLE user 
    ADD COLUMN preferences JSON NULL
    """)

def downgrade(db):
    db.execute("""
    ALTER TABLE user
    DROP COLUMN preferences
    """)

Documentation Guidelines

When contributing to the documentation:

1. Use Markdown for all documentation files
2. Keep language clear and concise
3. Include code examples where appropriate
4. Follow the existing documentation structure
5. Update the documentation when implementing new features

Release Process

Our release process follows these steps:

1. Features and bugfixes are merged into develop
2. When ready for release, we:
   • Create a release branch release/X.Y.Z
   • Update version number in version.py
   • Finalize CHANGELOG.md
   • Run final tests
3. The release branch is merged into main
4. A tag is created for the release
5. main is merged back into develop

Getting Help

If you need help or have questions:

• Check the existing documentation
• Look at similar features or patterns in the codebase
• Reach out on the project issues page
• Contact the maintainers directly

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Our Standards

• Be respectful and inclusive
• Accept constructive criticism gracefully
• Focus on what's best for the community
• Show empathy towards other community members

License

By contributing to Quizzical Beats, you agree that your contributions will be licensed under the project's MIT License.