mirror of
https://github.com/Serial-ATA/lofty-rs
synced 2024-12-13 14:12:31 +00:00
117 lines
4 KiB
Markdown
117 lines
4 KiB
Markdown
|
# 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;
|
||
|
|
}
|
||
|
|
```
|