Add a chapter on useful @rustbot commands

Author: LeSeulArtichaut

src/SUMMARY.md

@@ -31,6 +31,7 @@
 
 - [Introduction](./contributing.md)
 - [About the compiler team](./compiler-team.md)
+- [Mastering @rustbot](./rustbot.md)
 - [Walkthrough: a typical contribution](./walkthrough.md)
 - [Bug Fix Procedure](./bug-fix-procedure.md)
 - [Implementing new features](./implementing_new_features.md)

src/contributing.md

@@ -154,12 +154,17 @@ rebase when bringing the latest changes from the master branch to your feature
 branch.  Also, please make sure that fixup commits are squashed into other
 related commits with meaningful commit messages.
 
+If you encounter merge commits, your PR will get marked as `S-waiting-on-author`.
+When you resolve them, you should use `@rustbot` to mark it as `S-waiting-on-review`.
+See [this chapter][labeling] for more details.
+
 GitHub allows [closing issues using keywords][closing-keywords]. This feature
 should be used to keep the issue tracker tidy. However, it is generally preferred
 to put the "closes #123" text in the PR description rather than the issue commit;
 particularly during rebasing, citing the issue number in the commit can "spam"
 the issue in question.
 
+[labeling]: ./rustbot.md#issue-relabeling
 [closing-keywords]: https://help.github.com/en/articles/closing-issues-using-keywords
 
 ### External Dependencies (subtree)
@@ -413,8 +418,8 @@ still valid. Load up an older issue, double check that it's still true, and
 leave a comment letting us know if it is or is not. The [least recently
 updated sort][lru] is good for finding issues like this.
 
-Contributors with sufficient permissions on the Rust repo can help by adding
-labels to triage issues:
+[Thanks to `@rustbot`][rustbot], anyone can help triaging issues by adding
+appropriate labels to issues that haven't been triaged yet:
 
 * Yellow, **A**-prefixed labels state which **area** of the project an issue
   relates to.
@@ -435,7 +440,9 @@ labels to triage issues:
 
 * Red, **I**-prefixed labels indicate the **importance** of the issue. The
   [I-nominated][inom] label indicates that an issue has been nominated for
-  prioritizing at the next triage meeting.
+  prioritizing at the next triage meeting. Similarely, the [I-prioritize][ipri]
+  indicates that an issue has been requested to be prioritized by the
+  appropriate team.
 
 * The purple **metabug** label marks lists of bugs collected by other
   categories.
@@ -444,7 +451,7 @@ labels to triage issues:
   that this issue is specific to.
 
 * Orange, **P**-prefixed labels indicate a bug's **priority**. These labels
-  are only assigned during triage meetings, and replace the [I-nominated][inom]
+  are only assigned during triage meetings, and replace the [I-prioritize][ipri]
   label.
 
 * The gray **proposed-final-comment-period** label marks bugs that are using
@@ -464,7 +471,9 @@ labels to triage issues:
 
 If you're looking for somewhere to start, check out the [E-easy][eeasy] tag.
 
+[rustbot]: ./rustbot.md
 [inom]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AI-nominated
+[ipri]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AI-prioritize
 [eeasy]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy
 [lru]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-asc
 [rfcbot]: https://github.com/anp/rfcbot-rs/

src/rustbot.md

@@ -0,0 +1,62 @@
+# Mastering @rustbot
+
+`@rustbot` (also known as `triagebot`) is a utility robot that is mostly used to
+allow any contributor to achieve certain tasks that would normally require GitHub
+membership to the `rust-lang` organization. Its most interesting features for
+contributors to `rustc` are isssue claiming and relabeling.
+
+## Issue claiming
+
+`@rustbot` exposes a command that allows anyone to assign an issue to themselves.
+If you see an issue you want to work on, you can send the following message as a
+comment on the issue at hand:
+
+    @rustbot claim
+
+If you are a member of the `rust-lang` organization, `@rustbot` will assign the
+issue to you. Otherwise, `@rustbot` will assign itself as a placeholder and edit
+the top comment to reflect the fact that the issue is now assigned to you.
+
+If you want to unassign from an issue, `@rustbot` has a different command:
+
+    @rustbot release-assignment
+
+## Issue relabeling
+
+Changing labels for an issue or PR is also normally reserved to members of the
+organization. However, `@rustdoc` allows you to relabel an issue yourself, only
+with a few restrictions. This is mostly useful in two cases:
+
+**Helping with issue triage**: Rust's issue tracker has more than 5,000 open
+issues at the time of this writing, so labels are the most powerful tool that we
+have to keep it as tidy as possible. You may not spend hours in the issue tracker
+to triage issues, but if you open an issue, you should feel free to label it if
+you are comfortable with doing it yourself.
+
+**Updating the status of a PR**: we use "status labels" to reflect the status of
+PRs. For example, if your PR has merge conflicts, it will automatically be assigned
+the `S-waiting-on-author`, and reviewers might not review it until you rebase your
+PR. Once you did rebase your branch, you should change the labels yourself to remove
+the `S-waiting-on-author` label and add back `S-waiting-on-review`. In this case,
+the `@rustbot` command will look like this:
+
+    @rustbot modify labels: -S-waiting-on-author +S-waiting-on-review
+
+The syntax for this command is pretty loose, so there are other variants of this
+command invocation. For more details, see [the wiki page about labeling][labeling].
+
+[labeling]: https://github.com/rust-lang/triagebot/wiki/Labeling
+
+## Other commands
+
+If you are interested in seeing what `@rustbot` is capable of, check out its [wiki],
+which is meant as a reference for the bot and should be kept up to date every time the
+bot gets an upgrade.
+
+`@rustbot` is maintained by the Release team. If you have any feedback regarding
+existing commands or suggestions for new commands, feel free to reach out
+[on Zulip][zulip] or file an issue in [the triagebot repository][repo]
+
+[wiki]: https://github.com/rust-lang/triagebot/wiki
+[zulip]: https://rust-lang.zulipchat.com/#narrow/stream/224082-t-release.2Ftriagebot
+[repo]: https://github.com/rust-lang/triagebot/