mirror of
https://github.com/RustAudio/rodio
synced 2024-12-12 13:12:30 +00:00
dc85fe8045
- Encourage use of temporary unit tests during development - Clarify that rough, non-comprehensive tests are acceptable - Allow inclusion of temporary tests in pull requests - Explain rationale for removing tests before final merge: - Easier refactoring - Reduced necessity due to Rust's type system - Maintain instruction to run tests with 'cargo test'
121 lines
5 KiB
Markdown
121 lines
5 KiB
Markdown
# Rodio Development Guide
|
|
|
|
## Quick Start
|
|
|
|
1. Clone the repository: `git clone https://github.com/RustAudio/rodio.git`
|
|
2. Navigate to the project: `cd rodio`
|
|
3. Build the project: `cargo build`
|
|
|
|
## Project Structure
|
|
|
|
src/:
|
|
- `source/`: Audio source implementations
|
|
- `decoder/`: Audio format decoders
|
|
- `sink/`: Audio playback and mixing
|
|
- `dynamic_mixer/`: Real-time audio mixing
|
|
- `spatial/`: Spatial audio capabilities
|
|
|
|
## Coding Guidelines
|
|
|
|
- Follow [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
|
|
- Use `rustfmt` for formatting
|
|
- Implement `Source` trait for new audio sources
|
|
- Use `Sink` for playback management
|
|
|
|
## Common Tasks
|
|
|
|
### Adding a New Audio Source or Effect
|
|
|
|
1. Create a new file in `src/source/`
|
|
2. Implement the `Source` trait to define how audio samples are generated or modified
|
|
3. Consider implementing sources like oscillators, noise generators, or effects like amplification, filtering, or distortion
|
|
4. Begin with a test for your new feature. This approach ensures your PR is ready and simplifies development. Don't worry about optimizing initially; focus on functionality.
|
|
5. Once your feature works, celebrate your progress! 🎉 Open a draft PR at this stage - we're here to assist with refactoring and optimization.
|
|
6. Refactor your code, add benchmarks, and work on improving performance, especially for real-time processing in effects. Refer to the [Rust Performance Book](https://nnethercote.github.io/perf-book/introduction.html) for optimization techniques.
|
|
7. If you're unsure about creating tests, implement your feature first, then open a PR asking for guidance. We're happy to help!
|
|
|
|
### Implementing a New Decoder
|
|
|
|
1. Add new module in `src/decoder/`
|
|
2. Implement necessary traits (e.g., `Decoder`) to handle specific audio formats
|
|
3. Focus on efficiently parsing audio file headers and decoding compressed audio data
|
|
4. Update `src/decoder/mod.rs` to integrate the new decoder
|
|
|
|
## Testing
|
|
|
|
- Feel free to write temporary unit tests during development if they help you verify functionality
|
|
- These tests can be rough and don't need to be comprehensive - they're just development aids
|
|
- It's okay to include these temporary unit tests in your pull request
|
|
- We'll remove these tests before merging into the main codebase, primarily because:
|
|
- They can make refactoring more difficult as tests may break with code changes
|
|
- Rust's robust type system reduces the need for extensive unit testing compared to dynamically typed languages
|
|
- Run tests: `cargo test`
|
|
|
|
## Documentation
|
|
|
|
- Add inline documentation to all public items
|
|
- Generate docs: `cargo doc --open`
|
|
- Contribute examples to `examples/`
|
|
|
|
## Contribution Workflow
|
|
|
|
1. Fork the repository on GitHub
|
|
2. Clone your fork locally: `git clone https://github.com/YOUR_USERNAME/rodio.git`
|
|
3. Create a feature branch: `git checkout -b feature/your-feature-name`
|
|
4. Make changes and add tests where applicable (Dont be afraid to ask for help)
|
|
5. Ensure code quality:
|
|
- Run `cargo fmt` to format your code
|
|
- Run `cargo clippy` to check for common mistakes
|
|
- Run `cargo test` to ensure all tests pass (Not strictly necessary)
|
|
- Run `cargo bench` to run benchmarks (Not strictly necessary)
|
|
6. Commit your changes following these guidelines: (`git commit`)
|
|
- Write clear, concise commit messages
|
|
- Limit the first line to 50 characters
|
|
- Provide a detailed description after a blank line, if necessary
|
|
- Reference relevant issue numbers (e.g., "Fixes #123")
|
|
- Separate logical changes into multiple commits
|
|
- Avoid commits with unrelated changes
|
|
Example:
|
|
```
|
|
Add spatial audio support for stereo sources
|
|
|
|
- Implement SpatialSource struct
|
|
- Add panning and distance attenuation
|
|
- Update documentation for spatial audio usage
|
|
|
|
Fixes #456
|
|
```
|
|
7. Push your changes to your fork: `git push origin feature/your-feature-name`
|
|
8. Create a pull request on GitHub
|
|
|
|
## Getting Help / Got a question?
|
|
|
|
- Open an issue on GitHub
|
|
- Join the Rust Audio Discord
|
|
- Ask questions in your pull request
|
|
- Open an issue for guidance/questions
|
|
|
|
## Useful Commands
|
|
|
|
- Format: `cargo fmt` - Automatically formats the code according to Rust style guidelines
|
|
- Lint: `cargo clippy` - Runs the Clippy linter to catch common mistakes and improve code quality
|
|
- Benchmark: `cargo bench` - Executes performance benchmarks for the project
|
|
|
|
For more detailed information, refer to the full documentation and source code.
|
|
|
|
## Useful External Resources
|
|
|
|
- [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
|
|
- [Rust Performance Book](https://nnethercote.github.io/perf-book/introduction.html)
|
|
- [Rust Audio Discord](https://discord.com/invite/8qW6q2k)
|
|
|
|
## Disclaimer
|
|
|
|
Please note that the guidelines and practices outlined in this document
|
|
are not strict rules. They are general recommendations to promote
|
|
consistency and quality in contributions.
|
|
|
|
We understand that every situation is unique and encourage contributors
|
|
to use their best judgment. If you have any doubts or questions about
|
|
how to approach a particular task or contribution, don't hesitate to
|
|
reach out to the maintainers for guidance.
|