Document relabel aliases (#963)

Co-authored-by: Urgau <[email protected]>

Author: apiraino

src/compiler/backports.md

@@ -18,7 +18,7 @@ a [`T-compiler`] label as well.
 In any case, you should **add a comment when you nominate the pull request for backport** providing
 context for the compiler team backport reviewers about why it should be backported.
 
-**Backport nominations are not guaranteed be accepted**. Please refer to the [*Should the backport
+**Backport nominations are not guaranteed to be accepted**. Please refer to the [*Should the backport
 be approved*](#should-the-backport-be-approved) section below for the criteria on which backport
 nominations may be accepted or rejected.
 

src/release/issue-triaging.md

@@ -190,6 +190,10 @@ Triagebot needs to support `@rustbot label: xxx` usages terminated with a period
 - Check existing labels to make sure you're not duplicating them.
 - Discuss in <https://rust-lang.zulipchat.com/#narrow/channel/242269-t-release.2Ftriage/topic/New.20labels> if the new label may be non-conventional or controversial. Leave a comment about the new label as an FYI for others.
 
+### Label aliases
+
+Multiple labels can be added or removed in a single blow using *aliases*. Please visit the [relevant documentation][label-aliases] to learn more about aliases.
+
 ### Relnotes issues
 
 Release note issues will currently come with `needs-triage` by default. The triage for relnotes is usually best done if you have sufficient context. Leave them as-is if you don't.
@@ -255,6 +259,7 @@ Another useful thing to do is to go through `E-needs-mcve` and `E-needs-bisectio
 [`relnotes`]: https://github.com/rust-lang/rust/labels/relnotes
 [`metabug`]: https://github.com/rust-lang/rust/labels/metabug
 [relnotes issue example]: https://github.com/rust-lang/rust/issues/137132
+[label-aliases]: ../triagebot/labeling.html
 
 [^1]: The `O` in `O-*` labels originally stood for *operating system (OS)*.
 [^2]: The `I` in `I-*` labels originally stood for *importance*. This makes the most sense for the `I-*-nominated` labels. For most `I-*` labels however it makes sense to interpret the `I` as *issue (kind)*.

src/triagebot/labeling.md

@@ -15,6 +15,16 @@ Some examples:
 * `@rustbot label A-diagnostics A-macros`
 * `@rustbot label +T-lang -T-compiler` --- Removes `T-compiler` and adds `T-lang`.
 
+
+Labels are parsed and applied from left to right (canceling conflicting labels). Example:
+```
+# this command ...
+@rustbot label +Alpaca -Bench -Carlo +Esteban +Dwight +Bench
+
+# ... will be executed as:
+@rustbot label +Alpaca +Esteban +Dwight -Carlo
+```
+
 The syntax for the command is somewhat flexible, supporting a few different forms to suit your pleasure.
 Some examples of variants you can use:
 
@@ -81,6 +91,42 @@ allow-unauthenticated = [
 ]
 ```
 
+### Aliases
+
+The configuration also supports aliases, a single *word* that is expanded in a set of labels allowing setting multiple labels with a single command, useful when adding or removing the same set of labels over and over. To configure an alias, add to the triagebot the following item:
+```toml
+[relabel.alias-name]
+add-labels = ["Foo", "Bar"]
+rem-labels = ["Baz"]
+```
+
+`add-labels` and `rem-labels` and arrays of labels that the alias will expand to. For example, given the above configuration:
+```
+# the command
+@rustbot label alias-name
+
+# translates to
+@rustbot label +Foo +Bar -Baz
+```
+
+Aliases can also be *negative*, inverting the effect:
+```
+# this command
+@rustbot label -alias-name
+
+# translates to
+@rustbot label +Baz -Foo -Bar
+```
+
+You can also mix labels and aliases. Self-canceling labels will be omitted:
+```
+# this command
+@rustbot label alias-name +Baz
+
+# translates to:
+@rustbot label +Foo +Bar
+```
+
 ## Implementation
 
 See [`src/handlers/relabel.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/handlers/relabel.rs).