Contributing to Quizzical Beats¶

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

Getting Started¶

Development Environment Setup¶

Fork the repository on GitHub

Clone your fork locally:

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

Set up a virtual environment:

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

Install development dependencies:
```
pip install -r requirements-dev.txt
```
Set up pre-commit hooks:
```
pre-commit install
```

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¶

Create a new branch from develop:

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

Make your changes, following the coding standards
Run tests to ensure your changes don't break existing functionality:
```
pytest
```

Commit your changes with a descriptive message:

git commit -am "Add feature: short description

More detailed explanation of the changes if needed.
Fixes #123"

Push your branch to your fork:

git push origin feature/your-feature-name

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¶

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

Database Migrations¶

When making changes to the database schema:

Create a new migration script in the migrations/ directory
Name it descriptively (e.g., add_user_preferences.py)
Implement both upgrade and downgrade paths
Test the migration in both directions
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:

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

Release Process¶

Our release process follows these steps:

Features and bugfixes are merged into develop
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
The release branch is merged into main
A tag is created for the release
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.