diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..91a1de74 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,12 @@ +# Contributing to Lofty + +## [Issues](doc/ISSUES.md) + +Issues serve two purposes: + +* [Reporting bugs](doc/ISSUES.md#reporting-bugs) +* [Feature requests](doc/ISSUES.md#feature-requests) + +For any questions, you should use [the Q&A discussions page](https://github.com/Serial-ATA/lofty-rs/discussions/categories/q-a). + +## [Pull Requests](doc/PULL_REQUESTS.md) diff --git a/doc/ISSUES.md b/doc/ISSUES.md new file mode 100644 index 00000000..d9e20c2f --- /dev/null +++ b/doc/ISSUES.md @@ -0,0 +1,116 @@ +# Issues + +## Table of Contents + +1. [Before Reporting an Issue](#before-reporting-an-issue) +2. [Reporting Bugs](#reporting-bugs) + * [Issue Title](#issue-title) + * [Issue Summary](#issue-summary) + * [Reproducer](#reproducer) + * [Expected Behavior](#expected-behavior) + * [Actual Behavior](#actual-behavior) + * [Assets](#assets) + * [A Note on Copyright](#a-note-on-copyright) +3. [Feature Requests](#feature-requests) + * [Miscellaneous Feature Requests](#miscellaneous-feature-requests) + * [API Feature Requests](#api-feature-requests) + +## Before Reporting an Issue + +Before you report an issue, we ask that you do the following: + +1. **Search for existing issues**: Ensure that the issue you encountered has not already been reported by searching the issue tracker. +If you find a related issue, you can contribute by adding any additional information or subscribing to receive updates. + +2. **Update to the latest version**: Make sure you are using the most recent version of the project. +Sometimes, issues might have already been resolved in the latest release. + +## Reporting Bugs + +When reporting an issue, please provide as much relevant information as possible. +This will help us understand and address the problem efficiently. + +### Issue Title + +Choose a descriptive and concise title that summarizes the problem you encountered, +and the area it occurred in. A good title provides a clear idea of the issue at a glance. + +An example of a good title: "ID3v2: Tag padding is treated as a frame" + +### Issue Summary + +In the issue summary, provide a detailed explanation of the problem you are facing. + +Be specific and avoid ambiguity. Include information such as: + +* Any error/panic messages related to the problem. +* Any relevant configurations or settings you have modified. + +### Reproducer + +Include a set of clear and concise steps that can reproduce the issue you encountered. +These steps should be detailed enough for others to follow and observe the same problem. +Providing a minimal, standalone code example or a sample input can be immensely helpful. + +Unless necessary, please do not provide code with unnecessary context or inaccessible custom types. + +### Expected Behavior + +Describe what you expected to happen when you encountered the issue. +This information helps us understand the desired outcome and compare it to the actual behavior. + +### Actual Behavior + +Explain what actually happened when you encountered the issue. +Include any observed discrepancies or unexpected behavior. +This information will aid us in diagnosing the problem accurately. + +### Assets + +If applicable, provide any additional assets that might be relevant to the issue. +This can include files you have attempted to read, related discussions, +or links to relevant resources (specs, issues in other projects, etc.). + +#### A Note on Copyright + +Please do not upload copyrighted content to your issue. If there is an issue that you can only produce +with an asset that happens to be copyrighted, you can email it to `serial (AT) [domain on my profile]`. + +If you choose to email an asset, please be sure to state this in the issue. + +## Feature Requests + +There are two ways to create a feature request: + +* [Using the "[MISC] Feature Request" issue template](#miscellaneous-feature-requests) +* [Using the "[API] Feature Request" issue template](#api-feature-requests) + +### Miscellaneous Feature Requests + +The "[MISC] Feature Request" issue template is for feature requests that either: + +* Have no public API +* Are not fully fleshed out +* Implementation details are not too important + +### API Feature Requests + +The "[API] Feature Request" issue template is for feature requests that have a specific design. + +If you have an feature with an exact idea of how it should be used, be sure to use this template. + +The "API design" form should only serve as a design, not an implementation. + +For example, do this: + +```rust +pub struct MyTag { + some_field: ty, + some_other_field: ty, + // ... omit other fields if extending an existing type +} + +impl MyTag { + pub fn foo(&self) -> String; +} +``` diff --git a/doc/NEW_FILE.md b/doc/NEW_FILE.md new file mode 100644 index 00000000..89f2ca34 --- /dev/null +++ b/doc/NEW_FILE.md @@ -0,0 +1 @@ +# Adding a new file format diff --git a/doc/NEW_TAG.md b/doc/NEW_TAG.md new file mode 100644 index 00000000..df58d460 --- /dev/null +++ b/doc/NEW_TAG.md @@ -0,0 +1,2 @@ +# Adding a new tag format + diff --git a/doc/PULL_REQUESTS.md b/doc/PULL_REQUESTS.md new file mode 100644 index 00000000..5ecc75af --- /dev/null +++ b/doc/PULL_REQUESTS.md @@ -0,0 +1 @@ +# Pull Requests