From 5359b487f277e8fe86cf516e1cbec237b178c40a Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 16 Jan 2023 09:17:13 -0800 Subject: [PATCH] Add issue templates and update contributor docs --- .github/ISSUE_TEMPLATE/bug_report.yml | 45 ++++++++++++++++ .github/ISSUE_TEMPLATE/feature_request.yml | 28 ++++++++++ .github/ISSUE_TEMPLATE/question.yml | 24 +++++++++ CONTRIBUTING.md | 61 +++++++++++++++------- triagebot.toml | 21 ++++++-- 5 files changed, 156 insertions(+), 23 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/ISSUE_TEMPLATE/question.yml diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 00000000..1afb14a4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -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 diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 00000000..179fccd5 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -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. diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml new file mode 100644 index 00000000..6cce08c4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.yml @@ -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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 23f90c7a..e8f592d6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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! 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 -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). 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 -include documentation improvements, new tests, examples, updating dependencies, etc. +These issues can be a good launching pad for more involved issues. +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 [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-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. Issues on the issue tracker are categorized with the following labels: - **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. -- **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 -- **T**-prefixed labels show the type of issue +- **C**-prefixed labels show the category of issue ### 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. 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 ``` @@ -71,18 +80,15 @@ The quick guide is ``` 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) #### Finding Issues with Clippy -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 -help us maintain awesome code. - -The best documentation can be found over at [rust-clippy](https://github.com/rust-lang/rust-clippy) +[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 help us maintain awesome code. 1. To install ``` @@ -93,17 +99,36 @@ The best documentation can be found over at [rust-clippy](https://github.com/rus 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 . + +* 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 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. -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: ## Browser compatibility and testing diff --git a/triagebot.toml b/triagebot.toml index e7ecb6b3..9343d9ce 100644 --- a/triagebot.toml +++ b/triagebot.toml @@ -1,12 +1,23 @@ # This will allow users to self assign, and/or drop assignment [assign] +# Allows @rustbot ready, review, author, or blocked +[shortcut] [relabel] allow-unauthenticated = [ -# For Issue areas + # For Issue areas "A-*", - "E-Help-Wanted", - "Bug", - "Feature-Request" -] \ No newline at end of file + # Categories + "C-*", + # Commands + "Command-*", + # Status + "S-*", + "regression", + "Breaking Change", + "msrv-bump", +] + +[autolabel."S-waiting-on-review"] +new_pr = true