From 934d14eccf9cd9ad9f46263088a1104cf04ffb5f Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Sat, 5 Oct 2024 02:06:39 +0200
Subject: [PATCH] Contributing.md adds section on integration tests, improve
 new source section

Specifically notes some example tests and how they test. Also mentions
sometimes you just have to listen, recommands adding example for that.
---
 CONTRIBUTING.md | 30 ++++++++++++++++++++++--------
 1 file changed, 22 insertions(+), 8 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0112a0f7..cab4b036 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -27,12 +27,14 @@ src/:
 ### 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!
+1. Implement the `Source` trait to define how audio samples are generated or modified
+1. Consider implementing sources like oscillators, noise generators, or effects like amplification, filtering, or distortion
+1. If your contribution creates sound you should give it a public (factory) function that constructs it. If its an effect then add a method with default implementation for it in the `Source` trait.
+1. Begin with a test for your new feature (see the [Testing](#testing)). This approach ensures your PR is ready and simplifies development. Don't worry about optimizing initially; focus on functionality.
+1. Once your feature works, celebrate your progress! 🎉 Open a draft PR at this stage - we're here to assist with refactoring and optimization.
+1. 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.
+1. Finally add some documentation and an example. For details see [Documentation]($documentation)
+1. If you're unsure about creating tests, implement your feature first, then open a PR with what you have asking for guidance. We're happy to help!
 
 ### Implementing a New Decoder
 
@@ -49,13 +51,25 @@ src/:
 - 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
+- We love integration tests but they can be hard to write. If you have trouble adding one its fine to leave it out. If you do add one create a new file for it in `tests/`. 
+
+The integration test do not create sound though your speakers instead you write
+code that examines the produced *samples*. Some examples:
+  - The `tests/wav_test.rs` test simply checks if the decoder produces nonzero samples. 
+  - The test `seek_does_not_break_channel_order` in `tests/seek.rs` uses a
+    beeping sound that alternates between two channel. It seeks to a
+    point where we know only the second channel should make sound. Then we check
+    if the first channel is silent while the second is not.
+- Its impossible to write a test that checks if something sounds "good". We
+  recommend adding an example that *does* produces sound and listening as a
+  test.
 - Run tests: `cargo test`
 
 ## Documentation
 
-- Add inline documentation to all public items
+- Add inline documentation to all public items.
 - Generate docs: `cargo doc --open`
-- Contribute examples to `examples/`
+- Add an example. That could be as part of the inline documentation or a more complex scenario in `examples/`
 
 ## Contribution Workflow