Add issue templates and update contributor docs
This commit is contained in:
parent
41a6f0d43e
commit
5359b487f2
|
@ -0,0 +1,45 @@
|
||||||
|
name: Bug Report
|
||||||
|
description: Create a report to help us improve
|
||||||
|
labels: ["C-bug"]
|
||||||
|
body:
|
||||||
|
- type: markdown
|
||||||
|
attributes:
|
||||||
|
value: Thanks for filing a 🐛 bug report 😄!
|
||||||
|
- type: textarea
|
||||||
|
id: problem
|
||||||
|
attributes:
|
||||||
|
label: Problem
|
||||||
|
description: >
|
||||||
|
Please provide a clear and concise description of what the bug is,
|
||||||
|
including what currently happens and what you expected to happen.
|
||||||
|
validations:
|
||||||
|
required: true
|
||||||
|
- type: textarea
|
||||||
|
id: steps
|
||||||
|
attributes:
|
||||||
|
label: Steps
|
||||||
|
description: Please list the steps to reproduce the bug.
|
||||||
|
placeholder: |
|
||||||
|
1.
|
||||||
|
2.
|
||||||
|
3.
|
||||||
|
- type: textarea
|
||||||
|
id: possible-solutions
|
||||||
|
attributes:
|
||||||
|
label: Possible Solution(s)
|
||||||
|
description: >
|
||||||
|
Not obligatory, but suggest a fix/reason for the bug,
|
||||||
|
or ideas how to implement the addition or change.
|
||||||
|
- type: textarea
|
||||||
|
id: notes
|
||||||
|
attributes:
|
||||||
|
label: Notes
|
||||||
|
description: Provide any additional notes that might be helpful.
|
||||||
|
- type: textarea
|
||||||
|
id: version
|
||||||
|
attributes:
|
||||||
|
label: Version
|
||||||
|
description: >
|
||||||
|
Please paste the output of running `mdbook version` or which version
|
||||||
|
of the library you are using.
|
||||||
|
render: text
|
|
@ -0,0 +1,28 @@
|
||||||
|
name: Enhancement
|
||||||
|
description: Suggest an idea for enhancing mdBook
|
||||||
|
labels: ["C-enhancement"]
|
||||||
|
body:
|
||||||
|
- type: markdown
|
||||||
|
attributes:
|
||||||
|
value: |
|
||||||
|
Thanks for filing a 🙋 feature request 😄!
|
||||||
|
- type: textarea
|
||||||
|
id: problem
|
||||||
|
attributes:
|
||||||
|
label: Problem
|
||||||
|
description: >
|
||||||
|
Please provide a clear description of your use case and the problem
|
||||||
|
this feature request is trying to solve.
|
||||||
|
validations:
|
||||||
|
required: true
|
||||||
|
- type: textarea
|
||||||
|
id: solution
|
||||||
|
attributes:
|
||||||
|
label: Proposed Solution
|
||||||
|
description: >
|
||||||
|
Please provide a clear and concise description of what you want to happen.
|
||||||
|
- type: textarea
|
||||||
|
id: notes
|
||||||
|
attributes:
|
||||||
|
label: Notes
|
||||||
|
description: Provide any additional context or information that might be helpful.
|
|
@ -0,0 +1,24 @@
|
||||||
|
name: Question
|
||||||
|
description: Have a question on how to use mdBook?
|
||||||
|
labels: ["C-question"]
|
||||||
|
body:
|
||||||
|
- type: markdown
|
||||||
|
attributes:
|
||||||
|
value: |
|
||||||
|
Got a question on how to do something with mdBook?
|
||||||
|
- type: textarea
|
||||||
|
id: question
|
||||||
|
attributes:
|
||||||
|
label: Question
|
||||||
|
description: >
|
||||||
|
Enter your question here. Please try to provide as much detail as possible.
|
||||||
|
validations:
|
||||||
|
required: true
|
||||||
|
- type: textarea
|
||||||
|
id: version
|
||||||
|
attributes:
|
||||||
|
label: Version
|
||||||
|
description: >
|
||||||
|
Please paste the output of running `mdbook version` or which version
|
||||||
|
of the library you are using.
|
||||||
|
render: text
|
|
@ -7,13 +7,22 @@ If you have come here to learn how to contribute to mdBook, we have some tips fo
|
||||||
First of all, don't hesitate to ask questions!
|
First of all, don't hesitate to ask questions!
|
||||||
Use the [issue tracker](https://github.com/rust-lang/mdBook/issues), no question is too simple.
|
Use the [issue tracker](https://github.com/rust-lang/mdBook/issues), no question is too simple.
|
||||||
|
|
||||||
|
### Issue assignment
|
||||||
|
|
||||||
|
**:warning: Important :warning:**
|
||||||
|
|
||||||
|
Before working on pull request, please ping us on the corresponding issue.
|
||||||
|
The current PR backlog is beyond what we can process at this time.
|
||||||
|
Only issues that have an [`E-Help-wanted`](https://github.com/rust-lang/mdBook/labels/E-Help-wanted) or [`Feature accepted`](https://github.com/rust-lang/mdBook/labels/Feature%20accepted) label will likely receive reviews.
|
||||||
|
If there isn't already an open issue for what you want to work on, please open one first to see if it is something we would be available to review.
|
||||||
|
|
||||||
### Issues to work on
|
### Issues to work on
|
||||||
|
|
||||||
Any issue is up for the grabbing, but if you are starting out, you might be interested in the
|
If you are starting out, you might be interested in the
|
||||||
[E-Easy issues](https://github.com/rust-lang/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AE-Easy).
|
[E-Easy issues](https://github.com/rust-lang/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AE-Easy).
|
||||||
Those are issues that are considered more straightforward for beginners to Rust or the codebase itself.
|
Those are issues that are considered more straightforward for beginners to Rust or the codebase itself.
|
||||||
These issues can be a good launching pad for more involved issues. Easy tasks for a first time contribution
|
These issues can be a good launching pad for more involved issues.
|
||||||
include documentation improvements, new tests, examples, updating dependencies, etc.
|
Easy tasks for a first time contribution include documentation improvements, new tests, examples, updating dependencies, etc.
|
||||||
|
|
||||||
If you come from a web development background, you might be interested in issues related to web technologies tagged
|
If you come from a web development background, you might be interested in issues related to web technologies tagged
|
||||||
[A-JavaScript](https://github.com/rust-lang/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-JavaScript),
|
[A-JavaScript](https://github.com/rust-lang/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-JavaScript),
|
||||||
|
@ -21,16 +30,16 @@ If you come from a web development background, you might be interested in issues
|
||||||
[A-HTML](https://github.com/rust-lang/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-HTML) or
|
[A-HTML](https://github.com/rust-lang/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-HTML) or
|
||||||
[A-Mobile](https://github.com/rust-lang/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-Mobile).
|
[A-Mobile](https://github.com/rust-lang/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AA-Mobile).
|
||||||
|
|
||||||
When you decide you want to work on a specific issue, ping us on that issue so that we can assign it to you.
|
When you decide you want to work on a specific issue, and it isn't already assigned to someone else, assign the issue to yourself by leaving a comment with the text `@rustbot claim`.
|
||||||
Again, do not hesitate to ask questions. We will gladly mentor anyone that want to tackle an issue.
|
Again, do not hesitate to ask questions. We will gladly mentor anyone that want to tackle an issue.
|
||||||
|
|
||||||
Issues on the issue tracker are categorized with the following labels:
|
Issues on the issue tracker are categorized with the following labels:
|
||||||
|
|
||||||
- **A**-prefixed labels state which area of the project an issue relates to.
|
- **A**-prefixed labels state which area of the project an issue relates to.
|
||||||
- **E**-prefixed labels show an estimate of the experience necessary to fix the issue.
|
- **E**-prefixed labels show an estimate of the experience necessary to fix the issue.
|
||||||
- **M**-prefixed labels are meta-issues used for questions, discussions, or tracking issues
|
- **M**-prefixed labels are meta-issues regarding the management of the mdBook project itself
|
||||||
- **S**-prefixed labels show the status of the issue
|
- **S**-prefixed labels show the status of the issue
|
||||||
- **T**-prefixed labels show the type of issue
|
- **C**-prefixed labels show the category of issue
|
||||||
|
|
||||||
### Building mdBook
|
### Building mdBook
|
||||||
|
|
||||||
|
@ -59,7 +68,7 @@ This will ensure we have good quality source code that is better for us all to m
|
||||||
[rustfmt](https://github.com/rust-lang/rustfmt) has a lot more information on the project.
|
[rustfmt](https://github.com/rust-lang/rustfmt) has a lot more information on the project.
|
||||||
The quick guide is
|
The quick guide is
|
||||||
|
|
||||||
1. Install it
|
1. Install it (`rustfmt` is usually installed by default via [rustup](https://rustup.rs/)):
|
||||||
```
|
```
|
||||||
rustup component add rustfmt
|
rustup component add rustfmt
|
||||||
```
|
```
|
||||||
|
@ -71,18 +80,15 @@ The quick guide is
|
||||||
```
|
```
|
||||||
cargo fmt
|
cargo fmt
|
||||||
```
|
```
|
||||||
When run through `cargo` it will format all bin and lib files in the current crate.
|
When run through `cargo` it will format all bin and lib files in the current package.
|
||||||
|
|
||||||
For more information, such as running it from your favourite editor, please see the `rustfmt` project. [rustfmt](https://github.com/rust-lang/rustfmt)
|
For more information, such as running it from your favourite editor, please see the `rustfmt` project. [rustfmt](https://github.com/rust-lang/rustfmt)
|
||||||
|
|
||||||
|
|
||||||
#### Finding Issues with Clippy
|
#### Finding Issues with Clippy
|
||||||
|
|
||||||
Clippy is a code analyser/linter detecting mistakes, and therefore helps to improve your code.
|
[Clippy](https://doc.rust-lang.org/clippy/) is a code analyser/linter detecting mistakes, and therefore helps to improve your code.
|
||||||
Like formatting your code with `rustfmt`, running clippy regularly and before your Pull Request will
|
Like formatting your code with `rustfmt`, running clippy regularly and before your Pull Request will help us maintain awesome code.
|
||||||
help us maintain awesome code.
|
|
||||||
|
|
||||||
The best documentation can be found over at [rust-clippy](https://github.com/rust-lang/rust-clippy)
|
|
||||||
|
|
||||||
1. To install
|
1. To install
|
||||||
```
|
```
|
||||||
|
@ -93,17 +99,36 @@ The best documentation can be found over at [rust-clippy](https://github.com/rus
|
||||||
cargo clippy
|
cargo clippy
|
||||||
```
|
```
|
||||||
|
|
||||||
Clippy has an ever growing list of checks, that are managed in [lint files](https://rust-lang.github.io/rust-clippy/master/index.html).
|
### Change requirements
|
||||||
|
|
||||||
|
Please consider the following when making a change:
|
||||||
|
|
||||||
|
* Almost all changes that modify the Rust code must be accompanied with a test.
|
||||||
|
|
||||||
|
* Almost all features and changes must update the documentation.
|
||||||
|
mdBook has the [mdBook Guide](https://rust-lang.github.io/mdBook/) whose source is at <https://github.com/rust-lang/mdBook/tree/master/guide>.
|
||||||
|
|
||||||
|
* Almost all Rust items should be documented with doc comments.
|
||||||
|
See the [Rustdoc Book](https://doc.rust-lang.org/rustdoc/) for more information on writing doc comments.
|
||||||
|
|
||||||
|
* Breaking the API can only be done in major SemVer releases.
|
||||||
|
These are done very infrequently, so it is preferred to avoid these when possible.
|
||||||
|
See [SemVer Compatibility](https://doc.rust-lang.org/cargo/reference/semver.html) for more information on what a SemVer breaking change is.
|
||||||
|
|
||||||
|
(Note: At this time, some SemVer breaking changes are inevitable due to the current code structure.
|
||||||
|
An example is adding new fields to the config structures.
|
||||||
|
These are intended to be fixed in the next major release.)
|
||||||
|
|
||||||
|
* Similarly, the CLI interface is considered to be stable.
|
||||||
|
Care should be taken to avoid breaking existing workflows.
|
||||||
|
|
||||||
|
* Check out the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/) for guidelines on designing the API.
|
||||||
|
|
||||||
### Making a pull-request
|
### Making a pull-request
|
||||||
|
|
||||||
When you feel comfortable that your changes could be integrated into mdBook, you can create a pull-request on GitHub.
|
When you feel comfortable that your changes could be integrated into mdBook, you can create a pull-request on GitHub.
|
||||||
One of the core maintainers will then approve the changes or request some changes before it gets merged.
|
One of the core maintainers will then approve the changes or request some changes before it gets merged.
|
||||||
|
|
||||||
If you want to make your pull-request even better, you might want to run [Clippy](https://github.com/Manishearth/rust-clippy)
|
|
||||||
and [rustfmt](https://github.com/rust-lang/rustfmt) on the code first.
|
|
||||||
This is not a requirement though and will never block a pull-request from being merged.
|
|
||||||
|
|
||||||
That's it, happy contributions! :tada: :tada: :tada:
|
That's it, happy contributions! :tada: :tada: :tada:
|
||||||
|
|
||||||
## Browser compatibility and testing
|
## Browser compatibility and testing
|
||||||
|
|
|
@ -1,12 +1,23 @@
|
||||||
# This will allow users to self assign, and/or drop assignment
|
# This will allow users to self assign, and/or drop assignment
|
||||||
[assign]
|
[assign]
|
||||||
|
|
||||||
|
# Allows @rustbot ready, review, author, or blocked
|
||||||
|
[shortcut]
|
||||||
|
|
||||||
[relabel]
|
[relabel]
|
||||||
allow-unauthenticated = [
|
allow-unauthenticated = [
|
||||||
# For Issue areas
|
# For Issue areas
|
||||||
"A-*",
|
"A-*",
|
||||||
"E-Help-Wanted",
|
# Categories
|
||||||
"Bug",
|
"C-*",
|
||||||
"Feature-Request"
|
# Commands
|
||||||
|
"Command-*",
|
||||||
|
# Status
|
||||||
|
"S-*",
|
||||||
|
"regression",
|
||||||
|
"Breaking Change",
|
||||||
|
"msrv-bump",
|
||||||
]
|
]
|
||||||
|
|
||||||
|
[autolabel."S-waiting-on-review"]
|
||||||
|
new_pr = true
|
||||||
|
|
Loading…
Reference in New Issue