From d2772b88fef35ec82169e53c14e343c067c39bad Mon Sep 17 00:00:00 2001 From: Christian Krakau-Louis Date: Tue, 13 May 2025 21:56:58 +0200 Subject: [PATCH] Update README.md to reflect project renaming and enhance documentation; add multi-service music integration details and installation instructions; improve feature descriptions and security considerations. --- .github/ISSUE_TEMPLATE.md | 30 +++++ .github/PULL_REQUEST_TEMPLATE.md | 32 ++++++ CODE_OF_CONDUCT.md | 128 +++++++++++++++++++++ CONTRIBUTING.md | 54 +++++++++ README.md | 188 ++++++++++++++++++------------- 5 files changed, 353 insertions(+), 79 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 0000000..93b390b --- /dev/null +++ b/.github/ISSUE_TEMPLATE.md @@ -0,0 +1,30 @@ +# Issue Template + +## Description + +Provide a clear and concise description of the issue. Include any relevant context or screenshots to help explain the problem. + +## Steps to Reproduce + +1. Go to '...' +2. Click on '...' +3. Scroll down to '...' +4. See error + +## Expected Behavior + +Describe what you expected to happen. + +## Actual Behavior + +Describe what actually happened. + +## Environment + +- **OS**: [e.g., Windows 10, macOS 12.3] +- **Browser**: [e.g., Chrome 90, Firefox 88] +- **Version**: [e.g., 1.0.0] + +## Additional Context + +Add any other context about the problem here. \ No newline at end of file diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..7d10ffc --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,32 @@ +# Pull Request Template + +## Description + +Provide a brief description of the changes made in this pull request. Include the motivation and context for the change. + +Fixes # (issue) + +## 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 + +## Checklist + +- [ ] My code follows the style guidelines of this project +- [ ] I have performed a self-review of my own code +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] I have made corresponding changes to the documentation +- [ ] I have added tests that prove my fix is effective or that my feature works +- [ ] New and existing unit tests pass locally with my changes +- [ ] Any dependent changes have been merged and published in downstream modules + +## Screenshots (if applicable) + +Add screenshots to help explain your changes if applicable. + +## Additional Context + +Add any other context or information about the pull request here. \ No newline at end of file diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..52befd2 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,128 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +- Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or + advances of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email + address, without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +[contact email]. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..144c40e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,54 @@ +# Contributing to Quizzical Beats + +Thank you for considering contributing to Quizzical Beats! We welcome contributions of all kinds, including bug fixes, new features, documentation improvements, and more. + +## How to Contribute + +1. **Fork the Repository**: Start by forking the repository to your GitHub account. +2. **Clone Your Fork**: Clone your forked repository to your local machine: + ```bash + git clone https://github.com/christianlouis/QuizzicalBeats.git + cd QuizzicalBeats + ``` +3. **Set Up Your Environment**: Follow the [Getting Started](README.md#getting-started) guide in the README to set up your development environment. +4. **Create a Branch**: Create a new branch for your changes: + ```bash + git checkout -b feature/your-feature-name + ``` +5. **Make Your Changes**: Implement your changes, ensuring you follow the project's coding standards. +6. **Write Tests**: If applicable, add tests for your changes in the `tests/` directory. +7. **Run Tests**: Ensure all tests pass before submitting your changes: + ```bash + pytest + ``` +8. **Commit Your Changes**: Commit your changes with a descriptive commit message: + ```bash + git add . + git commit -m "Add feature: your feature description" + ``` +9. **Push Your Changes**: Push your branch to your forked repository: + ```bash + git push origin feature/your-feature-name + ``` +10. **Open a Pull Request**: Open a pull request from your branch to the `main` branch of the original repository. Provide a clear description of your changes and why they are necessary. + +## Code of Conduct + +This project adheres to the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. + +## Reporting Issues + +If you encounter any issues or have suggestions for improvements, please open an issue in the [GitHub Issues](https://github.com/christianlouis/QuizzicalBeats/issues) section. Provide as much detail as possible to help us understand and address the issue. + +## Style Guide + +- Follow [PEP 8](https://pep8.org/) for Python code. +- Use 4 spaces for indentation. +- Write clear and concise commit messages. +- Document your code where necessary, especially for complex logic. + +## License + +By contributing to Quizzical Beats, you agree that your contributions will be licensed under the [MIT License](LICENSE). + +Thank you for contributing to Quizzical Beats! \ No newline at end of file diff --git a/README.md b/README.md index 4aaa07d..60ab366 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,49 @@ -# MusicRound +# Quizzical Beats -**MusicRound** is a Flask-based web application for building engaging music rounds for pub quizzes. Leveraging the Spotify API, it allows you to generate rounds based on the least-used genres, decades, or completely random criteria, making your quizzes dynamic and entertaining. +

+ Quizzical Beats Logo +

+ +

+ 📚 Documentation • + Features • + Getting Started • + Deployment • + License +

+ +**Quizzical Beats** (formerly MusicRound) is a Flask-based web application for building engaging music quiz rounds for pub quizzes. Leveraging the Spotify and Deezer APIs, it allows you to generate rounds based on the least-used genres, decades, or completely random criteria, making your quizzes dynamic and entertaining. --- ## Features -- **Spotify Integration**: Import songs and playlists directly from Spotify using their API. +- **Multi-Service Music Integration**: + - **Spotify Integration**: Import songs and playlists directly from Spotify using their API. + - **Deezer Integration**: Alternative source for songs and playlists. + - **Last.fm Integration**: Automatically enrich tracks with genre metadata. + - **Dynamic Round Creation**: - - Randomly generated songs. + - Randomly generated rounds. - Based on least-used genres or decades. + - Tag-based rounds for custom categorization. - Unique and diverse song selections. -- **Preview and Export**: - - Include Spotify preview links in rounds. - - Export rounds as printable **PDFs** and playable **MP3s**. -- **Last.fm Integration**: Automatically enrich tracks with genre metadata. -- **Email Delivery**: Email generated quiz rounds to the designated recipient. + +- **Powerful Export Options**: + - Export rounds as printable **PDFs** with questions and answers. + - Create playable **MP3s** with song snippets. + - Generate **ZIP** packages with all round contents. + - **Dropbox Integration** for cloud storage of rounds. + +- **User Management**: + - Multiple authentication methods (local, Spotify, Google, Authentik). + - User-specific settings and preferences. + - Role-based access control. + +- **System Administration**: + - Comprehensive backup and restore functionality. + - System health monitoring dashboard. + - User and content management tools. --- @@ -23,22 +51,50 @@ ### Prerequisites -- **Python**: Version 3.6 or higher. +- **Python**: Version 3.9 or higher. - **Spotify Developer Account**: [Create a Spotify Developer App](https://developer.spotify.com/dashboard/applications) to retrieve your client ID and secret. - **Last.fm API Key**: Sign up at [Last.fm](https://www.last.fm/api) to obtain an API key. +- **Dropbox Developer Account** (optional): [Create a Dropbox App](https://www.dropbox.com/developers/apps) for export functionality. +- **Deezer Developer Account** (optional): [Create a Deezer App](https://developers.deezer.com/myapps) for additional music sources. ### Installation +#### Docker Installation (Recommended) + 1. Clone the repository: ```bash - git clone https://github.com/christianlouis/musicround.git - cd musicround + git clone https://github.com/christianlouis/QuizzicalBeats.git + cd QuizzicalBeats + ``` + +2. Configure environment variables in a `.env` file (copy from `.env.example`): + ```env + SPOTIFY_CLIENT_ID=your_spotify_client_id + SPOTIFY_CLIENT_SECRET=your_spotify_client_secret + SPOTIFY_REDIRECT_URI=http://localhost:5000/auth/spotify/callback + LASTFM_API_KEY=your_lastfm_api_key + # Add other configuration options as needed + ``` + +3. Start the Docker containers: + ```bash + docker-compose up -d + ``` + +4. Access the application at `http://localhost:5000`. + +#### Manual Installation + +1. Clone the repository: + ```bash + git clone https://github.com/christianlouis/QuizzicalBeats.git + cd QuizzicalBeats ``` 2. Create a virtual environment: ```bash - python3 -m venv venv - source venv/bin/activate + python -m venv venv + source venv/bin/activate # On Windows: venv\Scripts\activate ``` 3. Install dependencies: @@ -46,79 +102,62 @@ pip install -r requirements.txt ``` -4. Set up environment variables in a `.env` file: - ```env - SPOTIFY_CLIENT_ID=your_spotify_client_id - SPOTIFY_CLIENT_SECRET=your_spotify_client_secret - SPOTIFY_REDIRECT_URI=http://localhost:5000/callback - LASTFM_API_KEY=your_lastfm_api_key - ``` +4. Set up environment variables in a `.env` file (copy from `.env.example`). -5. Initialize the SQLite database: +5. Initialize the database: ```bash - python - >>> from app import db - >>> db.create_all() - >>> exit() + python run_migration.py ``` 6. Start the application: ```bash - python app.py + python run.py ``` -7. Open your browser and navigate to `http://localhost:5000`. +7. Access the application at `http://localhost:5000`. --- -## APIs Used +## Deployment -- **Spotify API**: - - Used to import songs, playlists, and retrieve song metadata. - - [API Documentation](https://developer.spotify.com/documentation/web-api/) +For production deployment, we recommend using Docker with proper security configurations. See our [Installation Guide](https://quizzicalbeats.readthedocs.io/admin-guide/installation.html) in the documentation for detailed deployment instructions. -- **Last.fm API**: - - Enriches tracks with genre information. - - [API Documentation](https://www.last.fm/api) +### Security Considerations -### Provided APIs - -**MusicRound** also provides APIs to fetch data from the application. For example: - -- `GET /rounds`: Fetch all rounds created. -- `POST /rounds`: Create a new round using specified criteria. -- `GET /songs`: Retrieve all songs in the database. - -For detailed API usage, refer to the in-app documentation or inspect the routes in `app.py`. +- Always use HTTPS in production +- Set up proper authentication methods +- Use strong, unique secrets and passwords +- Configure backups regularly --- -## Changelog +## Documentation -### Version 1.0 -- Initial release. -- Features: - - Spotify and Last.fm integration. - - Random, genre-based, and decade-based round generation. - - PDF and MP3 export functionality. - - Email delivery of rounds. +Comprehensive documentation is available at [quizzicalbeats.readthedocs.io](https://quizzicalbeats.readthedocs.io/), including: + +- [User Guide](https://quizzicalbeats.readthedocs.io/user-guide/getting-started.html) +- [Admin Guide](https://quizzicalbeats.readthedocs.io/admin-guide/installation.html) +- [Developer Guide](https://quizzicalbeats.readthedocs.io/developer-guide/architecture.html) +- [API Reference](https://quizzicalbeats.readthedocs.io/developer-guide/api-reference.html) +- [FAQ](https://quizzicalbeats.readthedocs.io/faq.html) --- ## Project Structure +The project follows a modular Flask application structure: + ``` -musicround/ -├── app.py # Main application logic -├── config.py # Configuration settings -├── templates/ # HTML templates for rendering views -├── static/ # Static files (CSS, JS) -├── requirements.txt # Python dependencies -├── instance/ # SQLite database folder -├── mp3/ # Audio files for MP3 generation -├── pdf_reports/ # Generated PDF reports -├── README.md # Project documentation -└── rounds/ # MP3 cache for quiz rounds +musicround/ # Main application package +├── __init__.py # Application factory +├── config.py # Configuration management +├── models.py # Database models +├── version.py # Version information +├── helpers/ # Utility modules +├── mp3/ # Audio file storage +├── routes/ # Route blueprints +├── static/ # Static assets +└── templates/ # HTML templates ``` --- @@ -131,22 +170,7 @@ This project is licensed under the **MIT License**. See `LICENSE` for details. ## Contributing -We welcome contributions! To contribute: - -1. Fork the repository. -2. Create a feature branch: - ```bash - git checkout -b feature/your-feature-name - ``` -3. Commit your changes: - ```bash - git commit -m "Add your feature description" - ``` -4. Push the branch: - ```bash - git push origin feature/your-feature-name - ``` -5. Open a pull request. +We welcome contributions! Please see our [Contributing Guide](https://quizzicalbeats.readthedocs.io/developer-guide/contributing.html) for details on how to get started. --- @@ -155,3 +179,9 @@ We welcome contributions! To contribute: - **Developer**: Christian Krakau-Louis - **Email**: [christian@kaufdeinquiz.com](mailto:christian@kaufdeinquiz.com) - **GitHub**: [christianlouis](https://github.com/christianlouis) + +--- + +

+ Where trivia meets the rhythm. +