diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..06d0f760 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,99 @@ +# Contribution Guidelines + +Thank you for your interest in contributing to Symphonia! + +There are many ways you may contribute. Some ideas for possible contributions are provided below. + +## Ways to Contribute + +### Implement new format readers, decoders, and features + +Implement missing features from the project roadmap, or features that haven't been considered yet. + +### Triage and fix reported issues + +Reproduce, root cause, and submit bug fixes for reported issues. + +### Benchmark and optimize + +Benchmark, identify, and report areas where performance could be improved. If possible, try your hand at optimizing it yourself! + +### Improve documentation + +Identify areas of the documentation that are lacking and expand them. Adding examples is another great way to help document the project for new users. + +### Test your content library + +Test your content library against Symphonia and ensure there are no panics or audio glitches. + +The [`symphonia-play`](symphonia-play/README.md) and [`symphonia-check`](symphonia-check/README.md) utilities may be used for this, but please note the section about interpreting results of the latter since false positives are not uncommon. + +### Answer questions + +Answer questions raised in issues or discussions. + +## Code & Documentation Contribution Guidelines + +Please read through these guidelines ahead of time to ensure a smooth contribution process. + +### General Considerations + +Symphonia is a mature project with a limited number of maintainers. Therefore, maintainability and preventing regressions are very important considerations when we accept contributions. + +We welcome pull requests (PRs) for new format readers, decoders, and other missing features. It is a good idea to raise an issue ahead of time to let everyone know what you will be working on to reduce the chance of duplicate efforts, and to make sure the change is aligned with the project. Once merged, please also consider volunteering to take responsibility for the on-going maintenance of the new code. + +While PRs containing isolated changes can usually be merged and included in the next release, PRs with the following changes may be delayed for some time: + +- SemVer or API breaking changes. Please read what constitutes a SemVer break in the Cargo [book](https://doc.rust-lang.org/cargo/reference/semver.html). +- Directly or indirectly increasing the minimum supported Rust version (MSRV). We consider this a SemVer breaking change. + +In general, we won't accept PRs for the following changes without prior discussion and approval: + +- Wholesale rewrites of a crate or feature. +- Replacing most, or all, of a crate or feature's implementation with an out-of-tree dependency. +- Changing an API or modifying the behaviour of Symphonia to specifically match the requirements of one project or application. + +### Quality + +Symphonia reads untrusted data which may be corrupted or deliberately malicious. It is critical that Symphonia validates and sanity-checks all data. Under no circumstance should Symphonia panic or consume an unbounded amount of system resources (e.g., RAM). + +A baseline level of quality is required before a PR is merged. All known audio glitches should be fixed, and the potential harm of any undiscovered audio glitch should be minimized. + +The build must be free of any warnings. + +Running clippy against the change is recommended, but not mandatory. Fuzzing is also recommended, but not mandatory. + +### Code Formatting + +Please format your code prior to submission with a **nightly** build of `rustfmt`. After installing the nightly toolchain you can do this by running `cargo +nightly fmt`. + +GitHub will not allow a PR to be merged that does not meet the code formatting standard. + +### Testing + +Adding unit tests for your code is recommended, but not mandatory. + +Please run `cargo test` before submission. + +GitHub will not allow a PR to be merged that has failing test cases. + +### Documentation + +If your change modifies the behaviour of a public +API, please also update the relevant documentation. This may also include [`GETTING_STARTED.md`](GETTING_STARTED.md) and any examples. + +If you reference any standards, please make note of it in the comments of your implementation. For example, if your code includes a lookup table of constants, add a comment indicating the standard and the section from which it came from. + +### Acknowledgements + +If you are a new contributor, please add yourself to the [`CONTRIBUTORS`](CONTRIBUTORS) file. + +If you are introducing a new crate, add yourself as the **first** author of the crate. + +### Commit History + +Unless otherwise requested, all PRs will be squashed into a single commit to maintain a clean history. If you would prefer that the commit history is kept, please ensure that it is clean. All commits should be meaningful and have a title that follows the general `component: Description of change.` style. + +### License + +Please be aware that all contributions must be licensed under the MPL v2.0 license. diff --git a/README.md b/README.md index 122928d3..50330116 100644 --- a/README.md +++ b/README.md @@ -201,6 +201,4 @@ Symphonia is provided under the MPL v2.0 license. Please refer to the LICENSE fi ## Contributing -Symphonia is an open-source project and contributions are very welcome! If you would like to make a large contribution, please raise an issue ahead of time to make sure your efforts fit into the project goals, and that there's no duplication of effort. Please be aware that all contributions must also be licensed under the MPL v2.0 license to be accepted. - -When submitting a pull request, be sure you have included yourself in the CONTRIBUTORS file! +Symphonia is a free and open-source project that welcomes contributions! To get started, please read our [Contribution Guidelines](CONTRIBUTING.md). diff --git a/symphonia-bundle-flac/README.md b/symphonia-bundle-flac/README.md index 1145795e..11164697 100644 --- a/symphonia-bundle-flac/README.md +++ b/symphonia-bundle-flac/README.md @@ -20,6 +20,4 @@ Symphonia is provided under the MPL v2.0 license. Please refer to the LICENSE fi ## Contributing -Symphonia is an open-source project and contributions are very welcome! If you would like to make a large contribution, please raise an issue ahead of time to make sure your efforts fit into the project goals, and that no duplication of efforts occurs. - -All contributors will be credited within the CONTRIBUTORS file. +Symphonia is a free and open-source project that welcomes contributions! To get started, please read our [Contribution Guidelines](https://github.com/pdeljanov/Symphonia/tree/master/CONTRIBUTING.md). diff --git a/symphonia-bundle-mp3/README.md b/symphonia-bundle-mp3/README.md index b590de5a..c851067f 100644 --- a/symphonia-bundle-mp3/README.md +++ b/symphonia-bundle-mp3/README.md @@ -20,6 +20,4 @@ Symphonia is provided under the MPL v2.0 license. Please refer to the LICENSE fi ## Contributing -Symphonia is an open-source project and contributions are very welcome! If you would like to make a large contribution, please raise an issue ahead of time to make sure your efforts fit into the project goals, and that no duplication of efforts occurs. - -All contributors will be credited within the CONTRIBUTORS file. +Symphonia is a free and open-source project that welcomes contributions! To get started, please read our [Contribution Guidelines](https://github.com/pdeljanov/Symphonia/tree/master/CONTRIBUTING.md). diff --git a/symphonia-check/README.md b/symphonia-check/README.md index d17c1ff8..6504885c 100644 --- a/symphonia-check/README.md +++ b/symphonia-check/README.md @@ -58,6 +58,4 @@ Symphonia is provided under the MPL v2.0 license. Please refer to the LICENSE fi ## Contributing -Symphonia is an open-source project and contributions are very welcome! If you would like to make a large contribution, please raise an issue ahead of time to make sure your efforts fit into the project goals, and that no duplication of efforts occurs. - -All contributors will be credited within the CONTRIBUTORS file. +Symphonia is a free and open-source project that welcomes contributions! To get started, please read our [Contribution Guidelines](https://github.com/pdeljanov/Symphonia/tree/master/CONTRIBUTING.md). diff --git a/symphonia-codec-aac/README.md b/symphonia-codec-aac/README.md index 798ebb8b..9214ddc5 100644 --- a/symphonia-codec-aac/README.md +++ b/symphonia-codec-aac/README.md @@ -20,6 +20,4 @@ Symphonia is provided under the MPL v2.0 license. Please refer to the LICENSE fi ## Contributing -Symphonia is an open-source project and contributions are very welcome! If you would like to make a large contribution, please raise an issue ahead of time to make sure your efforts fit into the project goals, and that no duplication of efforts occurs. - -All contributors will be credited within the CONTRIBUTORS file. +Symphonia is a free and open-source project that welcomes contributions! To get started, please read our [Contribution Guidelines](https://github.com/pdeljanov/Symphonia/tree/master/CONTRIBUTING.md). diff --git a/symphonia-codec-adpcm/README.md b/symphonia-codec-adpcm/README.md index bc8bb37b..8a738de5 100644 --- a/symphonia-codec-adpcm/README.md +++ b/symphonia-codec-adpcm/README.md @@ -21,6 +21,4 @@ Symphonia is provided under the MPL v2.0 license. Please refer to the LICENSE fi ## Contributing -Symphonia is an open-source project and contributions are very welcome! If you would like to make a large contribution, please raise an issue ahead of time to make sure your efforts fit into the project goals, and that no duplication of efforts occurs. - -All contributors will be credited within the CONTRIBUTORS file. +Symphonia is a free and open-source project that welcomes contributions! To get started, please read our [Contribution Guidelines](https://github.com/pdeljanov/Symphonia/tree/master/CONTRIBUTING.md). diff --git a/symphonia-codec-alac/README.md b/symphonia-codec-alac/README.md index 22c7027d..79c2ee04 100644 --- a/symphonia-codec-alac/README.md +++ b/symphonia-codec-alac/README.md @@ -12,6 +12,4 @@ Symphonia is provided under the MPL v2.0 license. Please refer to the LICENSE fi ## Contributing -Symphonia is an open-source project and contributions are very welcome! If you would like to make a large contribution, please raise an issue ahead of time to make sure your efforts fit into the project goals, and that no duplication of efforts occurs. - -All contributors will be credited within the CONTRIBUTORS file. +Symphonia is a free and open-source project that welcomes contributions! To get started, please read our [Contribution Guidelines](https://github.com/pdeljanov/Symphonia/tree/master/CONTRIBUTING.md). diff --git a/symphonia-codec-opus/README.md b/symphonia-codec-opus/README.md index 37432873..429b4140 100644 --- a/symphonia-codec-opus/README.md +++ b/symphonia-codec-opus/README.md @@ -10,6 +10,4 @@ Symphonia is provided under the MPL v2.0 license. Please refer to the LICENSE fi ## Contributing -Symphonia is an open-source project and contributions are very welcome! If you would like to make a large contribution, please raise an issue ahead of time to make sure your efforts fit into the project goals, and that no duplication of efforts occurs. - -All contributors will be credited within the CONTRIBUTORS file. +Symphonia is a free and open-source project that welcomes contributions! To get started, please read our [Contribution Guidelines](https://github.com/pdeljanov/Symphonia/tree/master/CONTRIBUTING.md). diff --git a/symphonia-codec-pcm/README.md b/symphonia-codec-pcm/README.md index d477a45e..ccecff53 100644 --- a/symphonia-codec-pcm/README.md +++ b/symphonia-codec-pcm/README.md @@ -37,6 +37,4 @@ Symphonia is provided under the MPL v2.0 license. Please refer to the LICENSE fi ## Contributing -Symphonia is an open-source project and contributions are very welcome! If you would like to make a large contribution, please raise an issue ahead of time to make sure your efforts fit into the project goals, and that no duplication of efforts occurs. - -All contributors will be credited within the CONTRIBUTORS file. +Symphonia is a free and open-source project that welcomes contributions! To get started, please read our [Contribution Guidelines](https://github.com/pdeljanov/Symphonia/tree/master/CONTRIBUTING.md). diff --git a/symphonia-codec-vorbis/README.md b/symphonia-codec-vorbis/README.md index ddcddd74..7c71e764 100644 --- a/symphonia-codec-vorbis/README.md +++ b/symphonia-codec-vorbis/README.md @@ -12,6 +12,4 @@ Symphonia is provided under the MPL v2.0 license. Please refer to the LICENSE fi ## Contributing -Symphonia is an open-source project and contributions are very welcome! If you would like to make a large contribution, please raise an issue ahead of time to make sure your efforts fit into the project goals, and that no duplication of efforts occurs. - -All contributors will be credited within the CONTRIBUTORS file. +Symphonia is a free and open-source project that welcomes contributions! To get started, please read our [Contribution Guidelines](https://github.com/pdeljanov/Symphonia/tree/master/CONTRIBUTING.md). diff --git a/symphonia-codec-wavpack/README.md b/symphonia-codec-wavpack/README.md index ad24c924..4ea19df2 100644 --- a/symphonia-codec-wavpack/README.md +++ b/symphonia-codec-wavpack/README.md @@ -12,6 +12,4 @@ Symphonia is provided under the MPL v2.0 license. Please refer to the LICENSE fi ## Contributing -Symphonia is an open-source project and contributions are very welcome! If you would like to make a large contribution, please raise an issue ahead of time to make sure your efforts fit into the project goals, and that no duplication of efforts occurs. - -All contributors will be credited within the CONTRIBUTORS file. +Symphonia is a free and open-source project that welcomes contributions! To get started, please read our [Contribution Guidelines](https://github.com/pdeljanov/Symphonia/tree/master/CONTRIBUTING.md). diff --git a/symphonia-core/README.md b/symphonia-core/README.md index 832fa40e..37c9b9dc 100644 --- a/symphonia-core/README.md +++ b/symphonia-core/README.md @@ -12,6 +12,4 @@ Symphonia is provided under the MPL v2.0 license. Please refer to the LICENSE fi ## Contributing -Symphonia is an open-source project and contributions are very welcome! If you would like to make a large contribution, please raise an issue ahead of time to make sure your efforts fit into the project goals, and that no duplication of efforts occurs. - -All contributors will be credited within the CONTRIBUTORS file. +Symphonia is a free and open-source project that welcomes contributions! To get started, please read our [Contribution Guidelines](https://github.com/pdeljanov/Symphonia/tree/master/CONTRIBUTING.md). diff --git a/symphonia-format-caf/README.md b/symphonia-format-caf/README.md index 7a648db2..073d7254 100644 --- a/symphonia-format-caf/README.md +++ b/symphonia-format-caf/README.md @@ -10,6 +10,4 @@ Symphonia is provided under the MPL v2.0 license. Please refer to the LICENSE fi ## Contributing -Symphonia is an open-source project and contributions are very welcome! If you would like to make a large contribution, please raise an issue ahead of time to make sure your efforts fit into the project goals, and that no duplication of efforts occurs. - -All contributors will be credited within the CONTRIBUTORS file. +Symphonia is a free and open-source project that welcomes contributions! To get started, please read our [Contribution Guidelines](https://github.com/pdeljanov/Symphonia/tree/master/CONTRIBUTING.md). diff --git a/symphonia-format-isomp4/README.md b/symphonia-format-isomp4/README.md index d11e8997..f7b68f71 100644 --- a/symphonia-format-isomp4/README.md +++ b/symphonia-format-isomp4/README.md @@ -12,6 +12,4 @@ Symphonia is provided under the MPL v2.0 license. Please refer to the LICENSE fi ## Contributing -Symphonia is an open-source project and contributions are very welcome! If you would like to make a large contribution, please raise an issue ahead of time to make sure your efforts fit into the project goals, and that no duplication of efforts occurs. - -All contributors will be credited within the CONTRIBUTORS file. +Symphonia is a free and open-source project that welcomes contributions! To get started, please read our [Contribution Guidelines](https://github.com/pdeljanov/Symphonia/tree/master/CONTRIBUTING.md). diff --git a/symphonia-format-mkv/README.md b/symphonia-format-mkv/README.md index 72ca5c50..bf85817e 100644 --- a/symphonia-format-mkv/README.md +++ b/symphonia-format-mkv/README.md @@ -10,6 +10,4 @@ Symphonia is provided under the MPL v2.0 license. Please refer to the LICENSE fi ## Contributing -Symphonia is an open-source project and contributions are very welcome! If you would like to make a large contribution, please raise an issue ahead of time to make sure your efforts fit into the project goals, and that no duplication of efforts occurs. - -All contributors will be credited within the CONTRIBUTORS file. +Symphonia is a free and open-source project that welcomes contributions! To get started, please read our [Contribution Guidelines](https://github.com/pdeljanov/Symphonia/tree/master/CONTRIBUTING.md). diff --git a/symphonia-format-ogg/README.md b/symphonia-format-ogg/README.md index 9f5c742b..22be6682 100644 --- a/symphonia-format-ogg/README.md +++ b/symphonia-format-ogg/README.md @@ -12,6 +12,4 @@ Symphonia is provided under the MPL v2.0 license. Please refer to the LICENSE fi ## Contributing -Symphonia is an open-source project and contributions are very welcome! If you would like to make a large contribution, please raise an issue ahead of time to make sure your efforts fit into the project goals, and that no duplication of efforts occurs. - -All contributors will be credited within the CONTRIBUTORS file. +Symphonia is a free and open-source project that welcomes contributions! To get started, please read our [Contribution Guidelines](https://github.com/pdeljanov/Symphonia/tree/master/CONTRIBUTING.md). diff --git a/symphonia-format-riff/README.md b/symphonia-format-riff/README.md index 8c1cbb77..01fa61d0 100644 --- a/symphonia-format-riff/README.md +++ b/symphonia-format-riff/README.md @@ -21,6 +21,4 @@ Symphonia is provided under the MPL v2.0 license. Please refer to the LICENSE fi ## Contributing -Symphonia is an open-source project and contributions are very welcome! If you would like to make a large contribution, please raise an issue ahead of time to make sure your efforts fit into the project goals, and that no duplication of efforts occurs. - -All contributors will be credited within the CONTRIBUTORS file. \ No newline at end of file +Symphonia is a free and open-source project that welcomes contributions! To get started, please read our [Contribution Guidelines](https://github.com/pdeljanov/Symphonia/tree/master/CONTRIBUTING.md). diff --git a/symphonia-format-wav/README.md b/symphonia-format-wav/README.md index 86e753bf..4d33627d 100644 --- a/symphonia-format-wav/README.md +++ b/symphonia-format-wav/README.md @@ -12,6 +12,4 @@ Symphonia is provided under the MPL v2.0 license. Please refer to the LICENSE fi ## Contributing -Symphonia is an open-source project and contributions are very welcome! If you would like to make a large contribution, please raise an issue ahead of time to make sure your efforts fit into the project goals, and that no duplication of efforts occurs. - -All contributors will be credited within the CONTRIBUTORS file. +Symphonia is a free and open-source project that welcomes contributions! To get started, please read our [Contribution Guidelines](https://github.com/pdeljanov/Symphonia/tree/master/CONTRIBUTING.md). diff --git a/symphonia-metadata/README.md b/symphonia-metadata/README.md index 7b485abd..54bdec72 100644 --- a/symphonia-metadata/README.md +++ b/symphonia-metadata/README.md @@ -12,6 +12,4 @@ Symphonia is provided under the MPL v2.0 license. Please refer to the LICENSE fi ## Contributing -Symphonia is an open-source project and contributions are very welcome! If you would like to make a large contribution, please raise an issue ahead of time to make sure your efforts fit into the project goals, and that no duplication of efforts occurs. - -All contributors will be credited within the CONTRIBUTORS file. +Symphonia is a free and open-source project that welcomes contributions! To get started, please read our [Contribution Guidelines](https://github.com/pdeljanov/Symphonia/tree/master/CONTRIBUTING.md). diff --git a/symphonia-play/README.md b/symphonia-play/README.md index 814ccc06..d2ed5fef 100644 --- a/symphonia-play/README.md +++ b/symphonia-play/README.md @@ -39,6 +39,4 @@ Symphonia is provided under the MPL v2.0 license. Please refer to the LICENSE fi ## Contributing -Symphonia is an open-source project and contributions are very welcome! If you would like to make a large contribution, please raise an issue ahead of time to make sure your efforts fit into the project goals, and that no duplication of efforts occurs. - -All contributors will be credited within the CONTRIBUTORS file. +Symphonia is a free and open-source project that welcomes contributions! To get started, please read our [Contribution Guidelines](https://github.com/pdeljanov/Symphonia/tree/master/CONTRIBUTING.md). diff --git a/symphonia-utils-xiph/README.md b/symphonia-utils-xiph/README.md index 47e3626f..22cc183f 100644 --- a/symphonia-utils-xiph/README.md +++ b/symphonia-utils-xiph/README.md @@ -12,6 +12,4 @@ Symphonia is provided under the MPL v2.0 license. Please refer to the LICENSE fi ## Contributing -Symphonia is an open-source project and contributions are very welcome! If you would like to make a large contribution, please raise an issue ahead of time to make sure your efforts fit into the project goals, and that no duplication of efforts occurs. - -All contributors will be credited within the CONTRIBUTORS file. +Symphonia is a free and open-source project that welcomes contributions! To get started, please read our [Contribution Guidelines](https://github.com/pdeljanov/Symphonia/tree/master/CONTRIBUTING.md). diff --git a/symphonia/README.md b/symphonia/README.md index 226852b2..9a243ce8 100644 --- a/symphonia/README.md +++ b/symphonia/README.md @@ -196,6 +196,4 @@ Symphonia is provided under the MPL v2.0 license. Please refer to the LICENSE fi ## Contributing -Symphonia is an open-source project and contributions are very welcome! If you would like to make a large contribution, please raise an issue ahead of time to make sure your efforts fit into the project goals, and that there's no duplication of effort. Please be aware that all contributions must also be licensed under the MPL v2.0 license to be accepted. - -When submitting a pull request, be sure you have included yourself in the CONTRIBUTORS file! +Symphonia is a free and open-source project that welcomes contributions! To get started, please read our [Contribution Guidelines](https://github.com/pdeljanov/Symphonia/tree/master/CONTRIBUTING.md).