Add CONTRIBUTING Guidelines

CONTRIBUTING.md

@@ -0,0 +1,121 @@
+# 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.