Thank you for your interest in contributing to pleezer! Your support is crucial to improving this project. This guide will help you understand how to report bugs, submit pull requests, and engage with our community.
pleezer takes a firm stance against piracy and copyright infringement. We are committed to:
- Supporting artists and content creators
- Maintaining compliance with Deezer's Terms of Service
- Protecting intellectual property rights
We will not:
- Accept contributions that enable or promote piracy
- Entertain discussions about circumventing content protection
- Support features designed for unauthorized content extraction
Any pull requests or issues related to such activities will be closed immediately without discussion.
pleezer is built on several key architectural decisions that guide our development:
-
Audio System Integration
- We use the Rodio library as our audio foundation
- Rodio was chosen for its robust cross-platform support and comprehensive audio backend abstraction
- Audio backend improvements should be contributed upstream to Rodio
- While Rodio supports numerous audio backends, we maintain this separation of concerns:
- Backend-specific improvements belong in Rodio
- If you need an unsupported backend, consider forking pleezer
-
Project Focus
- Our primary goal is to provide a high-quality headless player that integrates seamlessly with official Deezer clients
- While parts of pleezer may be useful as a library, alternative control methods are outside our scope
- We welcome contributions that:
- Improve modularity and extensibility
- Enhance the codebase's utility as a library
- Maintain our focus on the Deezer Connect protocol
-
Engineering Principles We value code that is:
- Strongly typed and panic-free
- Built around well-encapsulated newtypes
- Readable, correct, and idiomatic Rust
- Robust and maintainable
We require all contributors to adhere to our Code of Conduct, which ensures a respectful and constructive environment for everyone. The project is currently maintained by the author, who has the final decision-making authority. We expect all contributors to resolve any conflicts, either technical or interpersonal, in a manner that aligns with the Code of Conduct. The final decision on any conflicts rests with the author.
pleezer follows these standards to maintain clarity and consistency in our development process:
- Semantic Versioning for version numbering
- As we are currently below version 1.0.0, breaking changes may occur
- Breaking changes will be signified by a minor version bump
- The API is subject to refinement and updates during this phase
- Conventional Commits for commit messages
- Keep a Changelog for tracking changes
All significant changes are documented in our Changelog.
We follow Rust's idiomatic style and use rustfmt and clippy to enforce formatting and linting. Please ensure your code passes these checks before submitting a pull request.
Documentation is a crucial part of pleezer. We maintain several types of documentation:
-
API Documentation
- All public APIs must be documented using rustdoc
- Examples should be included where appropriate
- Documentation is published to docs.rs
-
User Documentation
- README.md contains quick start guide and basic usage
- Command-line help text via
--helpflag
-
Contributing Guidelines
- CONTRIBUTING.md (this document) for contributor information
- SECURITY.md for security-related procedures
- CODE_OF_CONDUCT.md for community guidelines
-
Change Documentation
- CHANGELOG.md following Keep a Changelog format
- GitHub releases with detailed release notes
When contributing:
- Ensure any new code includes appropriate rustdoc comments
- Update relevant documentation files
- Include code examples in rustdoc comments where they would help understanding
- Keep documentation in sync with code changes
Documentation PRs are highly valued and encouraged, even if they're not accompanied by code changes.
Our CI pipeline, managed with GitHub Actions, includes the following workflows:
- Cross-Compilation: Checks for cross-compilation on Rust stable with every push and pull request.
- Code Quality: Checks code formatting and linting on Rust stable using
rustfmtandclippy. - Weekly Maintenance: Periodically checks for compilation on Rust beta to ensure readiness for the next stable release of Rust.
Please ensure your code passes these checks before submitting a pull request.
We currently do not have a test harness. However, we encourage you to thoroughly test your changes using the built-in Rust testing framework before submitting a pull request.
While we do not have a formal performance testing process, manual testing is encouraged. Keep in mind that the minimum supported platform for pleezer is a Raspberry Pi 3B+ with 1GB of RAM.
pleezer is maintained by volunteers. We aim to review pull requests promptly, but response times may vary from a day to several weeks. If you feel a review is delayed, feel free to send a polite reminder. Peer reviews are also encouraged as the community grows.
- Check for Existing Issues: Before reporting a bug, search the issue tracker to avoid duplicates.
- Create a GitHub Issue: If the bug is new, create a GitHub issue and label it as "bug". Include as much detail as possible—steps to reproduce and logs are required.
- Submit as GitHub Issues: If you have an idea for a new feature, submit it as a GitHub issue with the "enhancement" label.
- Be Detailed: Provide clear details about the feature you're proposing to help us understand and prioritize it.
- Create a Branch: Always create a new branch for each feature or bug fix. Avoid committing directly to the
mainbranch. Use descriptive branch names. - Test Your Code: Ensure your code works as expected before submitting a pull request. Cross-platform testing is encouraged if possible.
- Update the Changelog: Update the Changelog with a summary of your changes under the "Unreleased" section. Follow the Keep a Changelog format.
- Open a Pull Request: Submit a pull request against the
mainbranch. Include a clear description of your changes and reference any related issues. Use descriptive and imperative commit messages. - Review Process: We will review your pull request as soon as possible, but response times can vary.
- Testing: While writing new tests is encouraged, it's not required at this stage as we do not yet have a test harness. Just make sure your code passes any existing tests.
- Documentation: Contributions to documentation are highly valued. If your pull request includes changes that require documentation updates, please include them.
We will acknowledge contributors in the release notes unless they choose to opt out. Sponsoring the project via GitHub Sponsors is also a meaningful way to contribute.
By contributing, you agree that your code will be licensed under the terms of the Sustainable Use License.
Please refer to the Security Policy for information on how to report security vulnerabilities. Do not use GitHub issues or discussions for reporting security vulnerabilities.
We aim for fast and frequent releases to ensure that improvements and fixes are delivered to users as quickly as possible. Our release process involves the following steps:
- Merge Pull Requests: Ensure all relevant pull requests are merged into the
mainbranch. - Update Changelog: Ensure the Changelog is up-to-date with the latest changes.
- Tag a New Release: Create a new tag for the release.
- Publish to Crates.io: Publish the new version to crates.io.
If you wish to support the project financially, you can do so through the GitHub Sponsors program for @roderickvd. Your support is greatly appreciated and will help ensure the continued development and improvement of pleezer.
We appreciate all contributions to pleezer. We will acknowledge contributors in the release notes unless they choose to opt out.