From 40d4e034b84ee246e0bff52c154cfa755831ed31 Mon Sep 17 00:00:00 2001 From: apiraino Date: Thu, 25 Jun 2020 21:52:13 +0200 Subject: [PATCH 01/18] update summary --- src/SUMMARY.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 8b289569f..d7cdc3a3c 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -1,11 +1,12 @@ # Rust Forge [Overview](./README.md) -- [Chat Platforms](./chat/README.md) +- [Platforms](./chat/README.md) - [Discord](./chat/discord.md) - [Email](./chat/email.md) - [Zulip](./chat/zulip.md) - [Moderation](./chat/zulip/moderation.md) + - [Triagebot](./chat/zulip/triagebot.md) - [Core](./core/README.md) - [Rust Blog Guidelines](./core/blogs.md) - [Legal counsel](./core/legal.md) From 8b4eb78696dd924342062962ef2a7e9f2689d861 Mon Sep 17 00:00:00 2001 From: apiraino Date: Thu, 25 Jun 2020 21:53:08 +0200 Subject: [PATCH 02/18] add triagebot docs --- src/chat/zulip/triagebot.md | 220 ++++++++++++++++++++++++++++++++++++ 1 file changed, 220 insertions(+) create mode 100644 src/chat/zulip/triagebot.md diff --git a/src/chat/zulip/triagebot.md b/src/chat/zulip/triagebot.md new file mode 100644 index 000000000..7b6d0e745 --- /dev/null +++ b/src/chat/zulip/triagebot.md @@ -0,0 +1,220 @@ +# Triagebot + +Triaging on the rust-lang repository is an important step to prepare the pipeline for the rust-lang teams that will take care of issues and regressions. The triagebot is the assistant for the rust-lang organization. + +To enable triagebot on a particular repository (currently only in the rust-lang organization), add a `triagebot.toml` file in the repository root. It should have a section per "feature". Please read this page to learn how to enable each feature and the options supported; if you spot something missing please let us know [by filing an issue](https://github.com/rust-lang/rust-forge/issues), thanks! + +- [Issue assignment](#issue-assignment) +- [Issue notifications](#issue-notifications) +- [Ping a team](#ping-a-team) +- [Glacier](#glacier) +- [Triage](#triage) +- [Applying labels to issues](#applying-labels-to-issues) +- [Requesting prioritization](#requesting-prioritization) +- [Major Changes](#major-changes) + +## Issue assignment + +Any user can claim an issue via `@rustbot claim`. Issues will be assigned to any user allowed to be an assignee. Users who don't will receive a "claimed" message in the top-level comment (and `rustbot` will be assigned). It is possible to override someone else's claim (no warning/error is given). + +You can drop your claim to the issue via `@rustbot release-assignment`; Rust team members can do the same if they want to release someone else's assignment. + +`@rustbot assign @user` can be used only by Rust team members and will assign that user to the issue (with same rules as before -- either directly or indirectly). + +Soon (when the "highfive" bot migration will be complete, see [rust-lang/highfive#258](https://github.com/rust-lang/highfive/pull/258)), `r?` will also assign users to PRs, though unlike issues, non-team members cannot be assigned. Anyone can invoke the command. + +To enable on a repository, add the following to a triagebot.toml file in the repository root. + +```toml +[assign] + +``` + +## Issue notifications + +Each registered team member has a notifications page at: + +`https://triagebot.infra.rust-lang.org/notifications?user=` + +This page is populated from direct mentions (@user) and team mentions (@rust-lang/libs) across the rust-lang organization. + +It can also be edited via Zulip by [private-messaging triagebot](https://rust-lang.zulipchat.com/#narrow/pm-with/261224-triage-rust-lang-bot). Any Rust organization member can edit their notifications page, or pages of other Rust organization team members. To do so, the editor must have a `zulip-id` listed in their people/username.toml file in the [team repository](https://github.com/rust-lang/team/). The bot will tell you which ID to use when talking to it for the first time; please `r? @Mark-Simulacrum` on PRs adding Zulip IDs. + +The following commands are supported: + + * `acknowledge ` + * `acknowledge ` + +These both acknowledge (and remove) a notification from the list. + + * `add ` + +This adds a new notification to the list. + + * `move ` + +This moves the notification at index `from` to the index `to`. + + * `meta ` + +This adds some text as a sub-bullet to the notification at `idx`. If the metadata is empty, the text is removed. + + * `as ` + +This executes any of the above commands as if you were the other GH user. + +## Ping a team + +The bot can be used to "ping" teams of people that do not have corresponding Github teams. This is useful because sometimes we want to keep groups of people that we can notify but we don't want to add all the members in those groups to the Github org, as that would imply that they are members of the Rust team (for example, Github would decorate their names with "member" and so forth). The compiler team uses this feature for their [ICE-breaker teams](https://rust-lang.github.io/rustc-guide/ice-breaker/about.html). + +TODO: isn't ICE-breakers now called [notification groups](https://rustc-dev-guide.rust-lang.org/notification-groups/about.html)? + +When a team is pinged, we will both post a message to the issue and add a label. The message will include a `cc` line that `@`-mentions all members of the team. + + +### Teams that can be pinged + +To be pinged, teams have to be created in the [Rust team repository]. Frequently those teams will be marked as `marker-team`, meaning that they do not appear on the website. The [LLVM ICE-breaker team] is an example. + +[Rust team repository]: https://github.com/rust-lang/team +[LLVM ICE-breaker team]: https://github.com/rust-lang/team/blob/master/teams/icebreakers-llvm.toml#L2 + +### Configuration + +To enable the team `XXX` (or "someothername") to be pinged, you have to add section to the `triagebot.toml` file at the root of a repository, like so: + +``` +[ping.XXX] +alias = ["someothername"] +message = """\ +Put your message here. It will be added as a Github comment, +so it can include Markdown and other markup. +""" +label = "help wanted" +``` + +This configuration would post the given message and also add the label `help wanted` to the issue. + +Check out [the rust-lang/rust configuration] for an up-to-date example. + +[the rust-lang/rust configuration]: https://github.com/rust-lang/rust/blob/master/triagebot.toml + +### Pinging teams + +To ping the team `XXX`, simply leave a comment with the command: + +``` +@rustbot ping XXX +``` + +### Related issues + +* Requested in [https://github.com/rust-lang/triagebot/issues/169](https://github.com/rust-lang/triagebot/issues/169) + +## Glacier + +This adds the option to track ICEs (Internal Compiler Errors). Do note that the GitHub Gist must be from a [Rust Playground](https://play.rust-lang.org) link. The link must also be in quotes (`""`), example: + +`@bot glacier "https://gist.github.com/rust-play/xxx"` + +## Triage + +This command will request the issue triaging (TODO: improve description) + +`@bot triage {high,medium,low,P-high,P-medium,P-low}` + +The configuration for this feature is: + +```toml +[triage] +remove = ["I-nominated"] # the set of labels to remove when this command is invoked +high = "P-high" +medium = "P-medium" +low = "P-low" +``` + +## Applying labels to issues + +Anyone can apply a label to issues. + +TODO: any updates [after this PR merge](https://github.com/rust-lang/triagebot/issues/591)? + +The specific grammar can be found [here](https://github.com/rust-lang/triagebot/blob/master/parser/src/command/relabel.rs), but some examples are listed below. The grammar is intended to be fairly intuitive for people, to prevent needing to reach for documentation when using the bot. + +``` +@rustbot modify labels to +T-lang, -T-compiler +``` + +This will remove the `T-compiler` label and add the `T-lang` label. You can also omit the `+` sign, if you want, and it'll be implied. + +You can also write the same command in a few other ways: + +``` +@rustbot modify labels to +T-lang and -T-compiler +@rustbot modify labels: +T-lang and -T-compiler +@rustbot modify labels to +T-lang and -T-compiler +``` + +Note that the command can either terminate with a `.` or a newline, otherwise the bot will not parse the command successfully. + +### Errors + +The bot currently restricts the labels that can be applied by people outside the Rust teams. For example, they can't add the I-unsound label. Most of the time, you shouldn't hit this. Feel free to ping the release team if you feel that a label should be added to the set of allowed labels! + +### Enabling +```toml +[relabel] +# any label is allowed to be set by team members (anyone on a team in rust-lang/team) +# but these can be set by anyone in the world +allow-unauthenticated = [ + "C-*", # any C- prefixed label will be allowed for anyone + # independent of authorization with rust-lang/team + "!C-bug", # but not C-bug (order does not matter) +] +``` + +## Requesting prioritization + +Users can request an issue to be prioritized by the Prioritization WG. + +To do so, you can invoke the following command: +```text +@rustbot prioritize +``` + +This will add the `I-prioritize` label to the issue, as well as creating a Zulip thread for the WG-prioritization members to discuss. + +### Errors +The command fails if the issue has already been requested for prioritization (i.e. already has the `I-prioritize` label). + +### Enabling +```toml +[prioritize] +# Name of the label used for requesting prioritization on issues +label = "I-prioritize" +# ID of the stream used by the Prioritization WG +zulip_stream = 227806 +``` + +## Major Changes + +A major change is an issue that will have a big impact on users. (TODO: improve description) + +The compiler team uses the major change process, which requires: + * An issue + * A second (TODO: replace term? The meaning could not be obvious to non-native English speakers) + +We have supporting automation for both parts. + +First, on the rust-lang/compiler-team repository, an issue with the "major-change" label (MCP = Major Change Proposal) is created via the template. Once that's opened, it automatically gains the "to-announce" label which should be removed when it's announced at a compiler team meeting. + +For seconds, you tell rustbot `@rustbot seconded` or `@rustbot second` and it will apply the relevant label. Only team members can do so. + +Configuration: +```toml +[major-change] +second_label = "final-comment-period" +meeting_label = "to-announce" +# can be found by looking for the first number in URLs, e.g. https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler +zulip_stream = 131828 +``` From ba68a1fe04c06fb2edaea8eda2dbb346feecc75e Mon Sep 17 00:00:00 2001 From: apiraino Date: Sat, 27 Jun 2020 19:05:12 +0200 Subject: [PATCH 03/18] Update src/chat/zulip/triagebot.md Co-authored-by: LeSeulArtichaut --- src/chat/zulip/triagebot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/chat/zulip/triagebot.md b/src/chat/zulip/triagebot.md index 7b6d0e745..440b806a9 100644 --- a/src/chat/zulip/triagebot.md +++ b/src/chat/zulip/triagebot.md @@ -119,7 +119,7 @@ This adds the option to track ICEs (Internal Compiler Errors). Do note that the ## Triage -This command will request the issue triaging (TODO: improve description) +This command can be used by people in charge of prioritizing issues, to assign either low or high priorities to issues. This is mostly done by the Compiler Prioritization WG for compiler bugs. `@bot triage {high,medium,low,P-high,P-medium,P-low}` From af0407ebf49f89dc0c5a274fde176781c121a316 Mon Sep 17 00:00:00 2001 From: apiraino Date: Sat, 27 Jun 2020 19:06:22 +0200 Subject: [PATCH 04/18] Update src/chat/zulip/triagebot.md Co-authored-by: LeSeulArtichaut --- src/chat/zulip/triagebot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/chat/zulip/triagebot.md b/src/chat/zulip/triagebot.md index 440b806a9..16ad43379 100644 --- a/src/chat/zulip/triagebot.md +++ b/src/chat/zulip/triagebot.md @@ -198,7 +198,7 @@ zulip_stream = 227806 ## Major Changes -A major change is an issue that will have a big impact on users. (TODO: improve description) +A major change is an issue that will have a big impact on users. See [this page on the MCP process](../../compiler/mcp.md) for detailed explanations. The compiler team uses the major change process, which requires: * An issue From befa258f62075753ec23a74437610ad2a2b72dea Mon Sep 17 00:00:00 2001 From: apiraino Date: Sat, 27 Jun 2020 19:07:47 +0200 Subject: [PATCH 05/18] Update src/chat/zulip/triagebot.md Co-authored-by: LeSeulArtichaut --- src/chat/zulip/triagebot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/chat/zulip/triagebot.md b/src/chat/zulip/triagebot.md index 16ad43379..a0ad9d1ab 100644 --- a/src/chat/zulip/triagebot.md +++ b/src/chat/zulip/triagebot.md @@ -202,7 +202,7 @@ A major change is an issue that will have a big impact on users. See [this page The compiler team uses the major change process, which requires: * An issue - * A second (TODO: replace term? The meaning could not be obvious to non-native English speakers) + * A "second", who is an expert from the Compiler team who thinks the proposal is a good idea We have supporting automation for both parts. From ad0c65329953d292bb419f3229563686d65d683a Mon Sep 17 00:00:00 2001 From: apiraino Date: Sat, 27 Jun 2020 19:08:16 +0200 Subject: [PATCH 06/18] Update src/chat/zulip/triagebot.md Co-authored-by: LeSeulArtichaut --- src/chat/zulip/triagebot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/chat/zulip/triagebot.md b/src/chat/zulip/triagebot.md index a0ad9d1ab..3b1a6bbb3 100644 --- a/src/chat/zulip/triagebot.md +++ b/src/chat/zulip/triagebot.md @@ -21,7 +21,7 @@ You can drop your claim to the issue via `@rustbot release-assignment`; Rust tea `@rustbot assign @user` can be used only by Rust team members and will assign that user to the issue (with same rules as before -- either directly or indirectly). -Soon (when the "highfive" bot migration will be complete, see [rust-lang/highfive#258](https://github.com/rust-lang/highfive/pull/258)), `r?` will also assign users to PRs, though unlike issues, non-team members cannot be assigned. Anyone can invoke the command. +Soon (when the "highfive" bot migration will be complete, see [rust-lang/highfive#258](https://github.com/rust-lang/highfive/pull/258)), `r?` will also assign reviewers to PRs, though unlike issues, non-team members cannot be assigned. Anyone can invoke the command. To enable on a repository, add the following to a triagebot.toml file in the repository root. From c6b927c976e581b2e372c1f275539bd8f2031b46 Mon Sep 17 00:00:00 2001 From: apiraino Date: Sat, 27 Jun 2020 19:08:54 +0200 Subject: [PATCH 07/18] Update src/chat/zulip/triagebot.md Co-authored-by: LeSeulArtichaut --- src/chat/zulip/triagebot.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/chat/zulip/triagebot.md b/src/chat/zulip/triagebot.md index 3b1a6bbb3..dee4d11f1 100644 --- a/src/chat/zulip/triagebot.md +++ b/src/chat/zulip/triagebot.md @@ -27,7 +27,6 @@ To enable on a repository, add the following to a triagebot.toml file in the rep ```toml [assign] - ``` ## Issue notifications From 11aaae1dde2266f069e0cbe4118bcbdee5790b6a Mon Sep 17 00:00:00 2001 From: apiraino Date: Sat, 27 Jun 2020 19:09:13 +0200 Subject: [PATCH 08/18] Update src/chat/zulip/triagebot.md Co-authored-by: LeSeulArtichaut --- src/chat/zulip/triagebot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/chat/zulip/triagebot.md b/src/chat/zulip/triagebot.md index dee4d11f1..4b686f3bb 100644 --- a/src/chat/zulip/triagebot.md +++ b/src/chat/zulip/triagebot.md @@ -114,7 +114,7 @@ To ping the team `XXX`, simply leave a comment with the command: This adds the option to track ICEs (Internal Compiler Errors). Do note that the GitHub Gist must be from a [Rust Playground](https://play.rust-lang.org) link. The link must also be in quotes (`""`), example: -`@bot glacier "https://gist.github.com/rust-play/xxx"` +`@rustbot glacier "https://gist.github.com/rust-play/xxx"` ## Triage From 326ec57d6ffab9243e37892e0a9cb5bcdd697869 Mon Sep 17 00:00:00 2001 From: apiraino Date: Sat, 27 Jun 2020 19:09:24 +0200 Subject: [PATCH 09/18] Update src/chat/zulip/triagebot.md Co-authored-by: LeSeulArtichaut --- src/chat/zulip/triagebot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/chat/zulip/triagebot.md b/src/chat/zulip/triagebot.md index 4b686f3bb..dc5114abf 100644 --- a/src/chat/zulip/triagebot.md +++ b/src/chat/zulip/triagebot.md @@ -120,7 +120,7 @@ This adds the option to track ICEs (Internal Compiler Errors). Do note that the This command can be used by people in charge of prioritizing issues, to assign either low or high priorities to issues. This is mostly done by the Compiler Prioritization WG for compiler bugs. -`@bot triage {high,medium,low,P-high,P-medium,P-low}` +`@rustbot triage {high,medium,low}` The configuration for this feature is: From c7edb6c6e4165ff577b29c0ca97b442d2e552be2 Mon Sep 17 00:00:00 2001 From: apiraino Date: Sat, 27 Jun 2020 19:09:43 +0200 Subject: [PATCH 10/18] Update src/chat/zulip/triagebot.md Co-authored-by: LeSeulArtichaut --- src/chat/zulip/triagebot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/chat/zulip/triagebot.md b/src/chat/zulip/triagebot.md index dc5114abf..40a73547b 100644 --- a/src/chat/zulip/triagebot.md +++ b/src/chat/zulip/triagebot.md @@ -181,7 +181,7 @@ To do so, you can invoke the following command: @rustbot prioritize ``` -This will add the `I-prioritize` label to the issue, as well as creating a Zulip thread for the WG-prioritization members to discuss. +This will simply add the `I-prioritize` label to the issue. ### Errors The command fails if the issue has already been requested for prioritization (i.e. already has the `I-prioritize` label). From e39e036c3200abf9f91998c5a7a03f4907b6e56a Mon Sep 17 00:00:00 2001 From: apiraino Date: Sat, 27 Jun 2020 19:09:56 +0200 Subject: [PATCH 11/18] Update src/chat/zulip/triagebot.md Co-authored-by: LeSeulArtichaut --- src/chat/zulip/triagebot.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/chat/zulip/triagebot.md b/src/chat/zulip/triagebot.md index 40a73547b..2266baf96 100644 --- a/src/chat/zulip/triagebot.md +++ b/src/chat/zulip/triagebot.md @@ -191,8 +191,6 @@ The command fails if the issue has already been requested for prioritization (i. [prioritize] # Name of the label used for requesting prioritization on issues label = "I-prioritize" -# ID of the stream used by the Prioritization WG -zulip_stream = 227806 ``` ## Major Changes From cfc10afc3718da87a8a3b4bf74c9504efb52f981 Mon Sep 17 00:00:00 2001 From: apiraino Date: Sat, 27 Jun 2020 19:10:07 +0200 Subject: [PATCH 12/18] Update src/chat/zulip/triagebot.md Co-authored-by: LeSeulArtichaut --- src/chat/zulip/triagebot.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/chat/zulip/triagebot.md b/src/chat/zulip/triagebot.md index 2266baf96..c69d5bea7 100644 --- a/src/chat/zulip/triagebot.md +++ b/src/chat/zulip/triagebot.md @@ -210,8 +210,11 @@ For seconds, you tell rustbot `@rustbot seconded` or `@rustbot second` and it wi Configuration: ```toml [major-change] +# Label to apply once an MCP is seconded second_label = "final-comment-period" +# Label to apply when an MCP is created meeting_label = "to-announce" -# can be found by looking for the first number in URLs, e.g. https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler +# The Zulip stream to automatically create topics about MCPs in +# Can be found by looking for the first number in URLs, e.g. https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler zulip_stream = 131828 ``` From 4d505da14dfd3340aa7223305424a1a390d8749b Mon Sep 17 00:00:00 2001 From: apiraino Date: Sat, 27 Jun 2020 21:11:20 +0200 Subject: [PATCH 13/18] misc update and fixes --- src/chat/zulip/triagebot.md | 35 +++++++++++++++++++---------------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/src/chat/zulip/triagebot.md b/src/chat/zulip/triagebot.md index c69d5bea7..67f05db22 100644 --- a/src/chat/zulip/triagebot.md +++ b/src/chat/zulip/triagebot.md @@ -1,6 +1,6 @@ # Triagebot -Triaging on the rust-lang repository is an important step to prepare the pipeline for the rust-lang teams that will take care of issues and regressions. The triagebot is the assistant for the rust-lang organization. +Triaging on the rust-lang repository is an important step to take care of issues. The triagebot is the tool that allows *anyone* to help by assigning, self-assigning or labeling issues without being a member of the rust-lang organization. To enable triagebot on a particular repository (currently only in the rust-lang organization), add a `triagebot.toml` file in the repository root. It should have a section per "feature". Please read this page to learn how to enable each feature and the options supported; if you spot something missing please let us know [by filing an issue](https://github.com/rust-lang/rust-forge/issues), thanks! @@ -15,7 +15,7 @@ To enable triagebot on a particular repository (currently only in the rust-lang ## Issue assignment -Any user can claim an issue via `@rustbot claim`. Issues will be assigned to any user allowed to be an assignee. Users who don't will receive a "claimed" message in the top-level comment (and `rustbot` will be assigned). It is possible to override someone else's claim (no warning/error is given). +Any user belonging to the rust-lang organization can claim an issue via `@rustbot claim`. If the user is not part of the rust-lang organization `rustbot` will choose an assignee and add a "claimed" message in the top-level comment, to signal who the current assignee is. It is possible to override someone else's claim (no warning/error is given). You can drop your claim to the issue via `@rustbot release-assignment`; Rust team members can do the same if they want to release someone else's assignment. @@ -64,27 +64,21 @@ This executes any of the above commands as if you were the other GH user. ## Ping a team -The bot can be used to "ping" teams of people that do not have corresponding Github teams. This is useful because sometimes we want to keep groups of people that we can notify but we don't want to add all the members in those groups to the Github org, as that would imply that they are members of the Rust team (for example, Github would decorate their names with "member" and so forth). The compiler team uses this feature for their [ICE-breaker teams](https://rust-lang.github.io/rustc-guide/ice-breaker/about.html). - -TODO: isn't ICE-breakers now called [notification groups](https://rustc-dev-guide.rust-lang.org/notification-groups/about.html)? +The bot can be used to "ping" teams of people that do not have corresponding Github teams. This is useful because sometimes we want to keep groups of people that we can notify but we don't want to add all the members in those groups to the Github org, as that would imply that they are members of the Rust team (for example, Github would decorate their names with "member" and so forth). The compiler team uses this feature to reach the [notification groups](https://rustc-dev-guide.rust-lang.org/notification-groups/about.html). When a team is pinged, we will both post a message to the issue and add a label. The message will include a `cc` line that `@`-mentions all members of the team. ### Teams that can be pinged -To be pinged, teams have to be created in the [Rust team repository]. Frequently those teams will be marked as `marker-team`, meaning that they do not appear on the website. The [LLVM ICE-breaker team] is an example. - -[Rust team repository]: https://github.com/rust-lang/team -[LLVM ICE-breaker team]: https://github.com/rust-lang/team/blob/master/teams/icebreakers-llvm.toml#L2 +To be pinged, teams have to be created in the [Rust team repository](https://github.com/rust-lang/team). Frequently those teams will be marked as `marker-team`, meaning that they do not appear on the website. The [LLVM team](https://github.com/rust-lang/team/blob/master/teams/icebreakers-llvm.toml#L2) is an example. ### Configuration -To enable the team `XXX` (or "someothername") to be pinged, you have to add section to the `triagebot.toml` file at the root of a repository, like so: +To enable the team (e.g. `TeamName`) to be pinged, you have to add section to the `triagebot.toml` file at the root of a repository, like so: ``` -[ping.XXX] -alias = ["someothername"] +[ping.TeamName] message = """\ Put your message here. It will be added as a Github comment, so it can include Markdown and other markup. @@ -94,9 +88,18 @@ label = "help wanted" This configuration would post the given message and also add the label `help wanted` to the issue. -Check out [the rust-lang/rust configuration] for an up-to-date example. +You can also define aliases to add additional labels to refer to same target team. Aliases can be useful to add mnemonic labels or accomodate slight mispellings (such as "llvms" instead "llvm"), see the following example: + +``` +[ping.cleanup-crew] +alias = ["llvm", "llvms"] +message = """\ +message content... +""" +``` + +Check out [the rust-lang/rust configuration](https://github.com/rust-lang/rust/blob/master/triagebot.toml) for an up-to-date examples. -[the rust-lang/rust configuration]: https://github.com/rust-lang/rust/blob/master/triagebot.toml ### Pinging teams @@ -116,6 +119,8 @@ This adds the option to track ICEs (Internal Compiler Errors). Do note that the `@rustbot glacier "https://gist.github.com/rust-play/xxx"` +where `xxx` is the SHA1 hash of the GitHub gist generated by the Playground "share" button. + ## Triage This command can be used by people in charge of prioritizing issues, to assign either low or high priorities to issues. This is mostly done by the Compiler Prioritization WG for compiler bugs. @@ -136,8 +141,6 @@ low = "P-low" Anyone can apply a label to issues. -TODO: any updates [after this PR merge](https://github.com/rust-lang/triagebot/issues/591)? - The specific grammar can be found [here](https://github.com/rust-lang/triagebot/blob/master/parser/src/command/relabel.rs), but some examples are listed below. The grammar is intended to be fairly intuitive for people, to prevent needing to reach for documentation when using the bot. ``` From ea4b9f239443029f15fe71adfeb408de45c6324f Mon Sep 17 00:00:00 2001 From: apiraino Date: Sat, 27 Jun 2020 21:24:45 +0200 Subject: [PATCH 14/18] File GitHub under the Platform section --- src/SUMMARY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index d7cdc3a3c..fc333c4fd 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -2,6 +2,7 @@ [Overview](./README.md) - [Platforms](./chat/README.md) + - [GitHub](./github.md) - [Discord](./chat/discord.md) - [Email](./chat/email.md) - [Zulip](./chat/zulip.md) @@ -32,7 +33,6 @@ - [Self-hosting a docs.rs instance](./docs-rs/self-hosting.md) - [Maintenance procedures](./docs-rs/maintenance.md) - [Migrating from a local database to S3](./docs-rs/migrate-s3.md) -- [GitHub](./github.md) - [Governance](./governance/README.md) - [Infrastructure](./infra/README.md) - [Other Installation Methods](./infra/other-installation-methods.md) From c539aaedd4e32bf76ca92608ab14b9f45bb20d6a Mon Sep 17 00:00:00 2001 From: apiraino Date: Sat, 27 Jun 2020 22:26:57 +0200 Subject: [PATCH 15/18] Move chat+github sections under platforms, update redirects --- book.toml | 6 + src/SUMMARY.md | 14 +- src/platforms/README.md | 5 + src/platforms/discord.md | 44 ++++++ src/platforms/email.md | 22 +++ src/{ => platforms}/github.md | 0 src/platforms/zulip.md | 196 ++++++++++++++++++++++++++ src/platforms/zulip/moderation.md | 31 +++++ src/platforms/zulip/triagebot.md | 223 ++++++++++++++++++++++++++++++ 9 files changed, 534 insertions(+), 7 deletions(-) create mode 100644 src/platforms/README.md create mode 100644 src/platforms/discord.md create mode 100644 src/platforms/email.md rename src/{ => platforms}/github.md (100%) create mode 100644 src/platforms/zulip.md create mode 100644 src/platforms/zulip/moderation.md create mode 100644 src/platforms/zulip/triagebot.md diff --git a/book.toml b/book.toml index 5b9bf45c9..683fe85f3 100644 --- a/book.toml +++ b/book.toml @@ -40,3 +40,9 @@ git-repository-url="https://github.com/rust-lang/rust-forge" "compiler/bug-fix-procedure.html" = "https://rustc-dev-guide.rust-lang.org/bug-fix-procedure.html" "compiler/diagnostic-codes.html" = "https://rustc-dev-guide.rust-lang.org/diagnostics/diagnostic-codes.html" "compiler/profile-queries.html" = "https://rustc-dev-guide.rust-lang.org/queries/profiling.html" +"chat/index.html" = "/platforms/index.html" +"chat/discord.html" = "platforms/discord.html" +"github.html" = "platforms/github.html" +"chat/email.html" = "platforms/email.html" +"chat/zulip/index.html" = "platforms/zulip/index.html" +"chat/zulip.html" = "platforms/zulip.html" \ No newline at end of file diff --git a/src/SUMMARY.md b/src/SUMMARY.md index fc333c4fd..84673aa1e 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -1,13 +1,13 @@ # Rust Forge [Overview](./README.md) -- [Platforms](./chat/README.md) - - [GitHub](./github.md) - - [Discord](./chat/discord.md) - - [Email](./chat/email.md) - - [Zulip](./chat/zulip.md) - - [Moderation](./chat/zulip/moderation.md) - - [Triagebot](./chat/zulip/triagebot.md) +- [Platforms](./platforms/README.md) + - [Discord](./platforms/discord.md) + - [Email](./platforms/email.md) + - [GitHub](./platforms/github.md) + - [Zulip](./platforms/zulip.md) + - [Moderation](./platforms/zulip/moderation.md) + - [Triagebot](./platforms/zulip/triagebot.md) - [Core](./core/README.md) - [Rust Blog Guidelines](./core/blogs.md) - [Legal counsel](./core/legal.md) diff --git a/src/platforms/README.md b/src/platforms/README.md new file mode 100644 index 000000000..e58c0afc6 --- /dev/null +++ b/src/platforms/README.md @@ -0,0 +1,5 @@ +## Platforms + +Rust uses a number of different platforms for organizing work and internal communications between +teams. This does not currently seek to be an exhaustive list, rather documenting +the policies for a select few platforms used by the teams. diff --git a/src/platforms/discord.md b/src/platforms/discord.md new file mode 100644 index 000000000..eb9044c57 --- /dev/null +++ b/src/platforms/discord.md @@ -0,0 +1,44 @@ +## Discord + +Rust's Discord is currently used by a variety of teams such as Community, Ops, and Documentation, as well as their working groups. It is also maintained as a communication tool for Domain Working Groups, and provides a space for general discussion among Rust users, contributors, and beginners. + +# Where to go for help with using Discord +Discord's support center provides documentation about its [user interface](https://support.discordapp.com/hc/en-us/categories/200404398) and [account settings](https://support.discordapp.com/hc/en-us/categories/200404358). + +# Getting started + +1) Understand community standards
+Discord, like all official Rust spaces, is governed by the Code of Conduct. Before joining the conversation there, you can prepare by reading the [Code of Conduct and Moderation Guidelines](https://www.rust-lang.org/community#conduct). +It is also useful to read [Discord's Community Guidelines](https://discordapp.com/guidelines) + +2) Access channels
+To access the Rust Discord, visit [https://discord.gg/rust-lang](https://discord.gg/rust-lang). If you do not already have a Discord account, you can register for one as part of the process of gaining access. Your first action should be agreeing to our Code of Conduct by following the instructions in #welcome. + +3) Configure notifications
+It is a good idea to disable notifications for channels that are not relevant to you, so that you will not be overwhelmed with messages. +Select the expansion arrow next to the server name banner (titled "The Rust Programming Language") and select Notifications from the dropdown. Then follow the configuration instructions provided [on the Discord Support site](https://support.discordapp.com/hc/en-us/articles/215253258-Notifications-Settings-101). + +# Appropriate conversation +Discussions should be related to the channel purpose. On team channels, conversation should be related to team business. +All channels are expected to be used for purposes related to the Rust project. Discussion of (for example) wildlife or sightseeing are not appropriate. + +# Channels + +The following channels are relevant to newcomers to the Rust project: +* welcome - Where you agree to the CoC. +* rust-usage - This is a channel where you can access support for resolving specific language use questions. The [Rust Users Forum](https://users.rust-lang.org/) is also relevant to your needs. +* beginners - Here, you can meet people who began using Rust relatively recently. +* contribute - Interested in contributing to the Rust project? In addition to joining this channel, you can subscribe to the [This Week In Rust](https://this-week-in-rust.org/) newsletter, where many opportunities are regularly posted. +It may also help to find out more about [specific teams](https://www.rust-lang.org/governance#teams). + +Channels outside of General are for contributors to Rust. + +# Messages +Discord conversation takes place when people are available, so you should not generally expect that your messages will receive a response quickly unless a meeting is taking place. Depending on how your notifications are configured, you will see a red circle on top of the Discord icon in your system tray when new messages are received. If you wish to communicate with a specific individual, right-click on their user icon and select "Message" in the dropdown menu. + +# Read-only view +Set up a Discord account (as described in Getting Started, above) in order to access Discord. There is not +currently a read-only archive view available. + + + diff --git a/src/platforms/email.md b/src/platforms/email.md new file mode 100644 index 000000000..fa47ca024 --- /dev/null +++ b/src/platforms/email.md @@ -0,0 +1,22 @@ +# Email + +While most of Rust's discussion happens on other platforms, email is eternal and +we occasionally need a way to approach individuals or groups privately. Our +email is hosted through Mailgun (provided by Mozilla). We create and edit the +mailing lists for teams through the [rust-lang/team] repository. Our email +domain is `rust-lang.org`, e.g. `ferris@rust-lang.org`. + +## Sending a public broadcast +If your teams need to reach everyone in Rust organisation they can send a +email to `all@`. It is recommended that you only use this mailing list when you +know that you need contact every member, such as for organising a members event +like the All Hands, or security alerts. + +### Keeping responses private +When sending a message to `all@`, do not put `all@` in `To`. This will mean that +any replies to your broadcast will also be sent to everyone. Instead put your +team's email address in `To` field, and place `all@` in the `Bcc` field. Then +any replies will be sent to just your team. + + +[rust-lang/team]: https://github.com/rust-lang/team diff --git a/src/github.md b/src/platforms/github.md similarity index 100% rename from src/github.md rename to src/platforms/github.md diff --git a/src/platforms/zulip.md b/src/platforms/zulip.md new file mode 100644 index 000000000..a9e98aec9 --- /dev/null +++ b/src/platforms/zulip.md @@ -0,0 +1,196 @@ +# Zulip + +[Rust's Zulip](https://rust-lang.zulipchat.com) is used by a number of teams, notably +the compiler, language, and library teams, along with their working groups. + +Zulip can be an unintuitive platform to get started with. To get started, take a +look at the [getting started +guide](https://zulipchat.com/help/getting-started-with-zulip). For more detail, +examine the [Zulip user documentation](https://zulipchat.com/help/)! + +## Where to go for help with using Zulip + +If you're testing a feature, or want to get help, the `#zulip` stream is the +place to go. Like elsewhere, the best thing to do is to create a new topic +for each question. + +## Getting started + +It is recommended to first look at the official [getting started +guide](https://zulipchat.com/help/getting-started-with-zulip). Like Rust itself, +Zulip is a bit special and reading the documentation before digging can be +really helpful. + +You'll definitely want to configure the streams that you're subscribed to when +getting started; the default set is quite limited, and there are many groups +that exist beyond it. Subscribing to a stream is very low cost -- it is similar +to being "in" an IRC channel, except that logs are available for all streams, +regardless of subscription status. + +It's not necessary to introduce yourself, but feel free to say hello in the +`#new members` stream. + +## User groups + +User groups can be pinged by anyone with the `@` notation, same as +pinging another user. Groups can be created by anyone, and anyone can join a +group. + +Users should feel free to join (or leave) groups on their own. Furthermore, +users should feel free to create groups as needed, though it is currently +expected that this is somewhat rare. You should name your group similar to how +you would name a stream for the same purpose, though groups can be more +fine-grained (or less). For example, `@T-compiler/meeting` currently does not +have a dedicated stream. + +## Appropriate conversation + +In most streams, you should try to keep conversations related to team business. +The `#general` stream is a bit broader, but even there, discussions should be +closely related to Rust (though may not relate to projects of any particular +team). All channels are expected to be used for discussions related to the Rust +project, though; discussions of (for example) wildlife or sightseeing are not +appropriate. + +## Streams + +These are similar to "channels" on other platforms (i.e., there should not be +too many). On the other hand, you can choose which streams you subscribe to, so +there can be more than channels on other platforms. Read [Zulip's +documentation](https://zulipchat.com/help/about-streams-and-topics) for more +details. + +Streams are appropriate for any Rust official group. For example, working +groups, project groups, teams are all examples of official groups. These should +ideally also be represented in the [team repository](../infra/team-maintenance.md). + +### Default streams + +**This section is still under debate, and it is not yet clear which direction we +will go. It is non-normative, and should not be used yet for modifications to +the Zulip instance.** + +The default set of streams is chosen to allow incoming people to be able to have +at least one place to go that can then, if necessary, direct them to a more +specific location. + +Currently that means that every top-level group present on Zulip is by default +visible. Specifically, no stream that contains a `/` will be enabled by default. + +Currently this set is: + * general + * t-lang + * t-compiler + * t-libs + * project-ffi-unwind + * project-inline-asm + * project-safe-transmute + * rust-survey-2019 + * wg-async-foundations + * wg-database + * wg-formal-methods + * wg-secure-code + * wg-traits + * zulip + +An alternative, minimalistic, approach is to use: + * general + * zulip + * announce + * new members + +as the default set, which would push people into customizing their default set when +starting out. + +### Stream naming + +A stream should be named such as `#t-{team}/{group name}`. For example, +`#t-compiler/wg-parallel-rustc`. More levels of nesting are fine, e.g., a +working group might want "subgroups" as well, though you may want to omit the +team name in such a case -- keeping the stream name short is good for usability, +to avoid confusion between different streams which share the same prefix. + +If no top-level team exists, or the group spans multiple teams (e.g., +project-ffi-unwind), then the top level team should be omitted. + +Streams should be clearly communicated as being for a specific purpose. That +purpose can be broad, but it should likely include a group of some kind (even if +that group is transient, e.g., people who are having trouble with the rust build +system, or people working on the compiler). Furthermore, we do not currently +intend for this Zulip to be a general place for community projects not +affiliated with the Rust organization; if they wish to use Zulip, it is [free +for open source](https://zulipchat.com/for/open-source/). + +When a new stream is created, you should announce it in `#announce`. This is +generally done automatically by Zulip. + +## Topics + +A topic is attached to every message within a given stream (these are the +subdivisions within streams). Topics are generally transient, and live for as +long as there is active discussion on a topic. Thinking of topics like email +subjects is helpful. + +New conversation in a given stream should almost always start in a new topic, +not a preexisting one. Unlike (for example) GitHub issues, you should not +attempt to search for a past topic on the same subject. Do not spend too long on +the name of the topic, either, beyond trying to make it short. Topics should +generally be no longer than 20 characters (loosely two to three words), to make +sure it is visible to users. + +You should eagerly fork new discussion topics into fresh topics. Note that this +can be done with the tail of another topic (if accidentally you diverge into +another area of discussion). + +To fork from an existing topic, see Zulip's documentation +[here](https://zulipchat.com/help/rename-a-topic). + +## Messages + +Zulip is a unique platform which combines synchronous and +asynchronous communication in one location. You should not generally expect that +your messages will receive a response quickly, and unlike (for example) Discord, +there is likely not much reason to "re-ping" on a particular issue every few +hours as your message is unlikely to vanish into history, being isolated to a +specific topic. + +### Linkifiers + +Our Zulip supports a lot of helpful linkifiers, and we're generally happy to add +more on request. See [the +documentation](https://rust-lang.zulipchat.com/help/add-a-custom-linkification-filter) +for the format. Propose one in `#zulip`! + +Generally, `github-org/repo#123` works for linking to an issue or PR; the below +list gives a few more "special cased" repositories. + +Don't forget that standard Markdown syntax for links also works. + +We currently support linking to issues on a few repositories: + +* rust-lang/rust with [`#4545`](https://github.com/rust-lang/rust/issues/4545) or `rust#4545` +* rust-lang/rfcs with `RFC#3434` or `rfc#3434` +* rust-lang/async-book with `async-book#2334` +* rust-lang-nursery/chalk with `chalk#2334` +* rust-lang/compiler-team with `compiler-team#3433` +* rust-lang-nursery/ena with `ena#3434` +* rust-lang/miri with `miri#3434` +* rust-lang-nursery/polonius with `polonius#3434` +* rust-analyzer/rust-analyzer with `rust-analyzer#3434` +* rust-lang/rustc-dev-guide with `rustc-dev-guide#3434` +* rust-lang/stdarch with `stdarch#3434` +* rust-lang/team with `team#3434` +* rust-lang/unsafe-code-guidelines with `ucg#3434` + +We currently support linking to commits on these repositories: + +* rust-lang/rust with 40-character long SHAs, e.g., [`25434f898b499876203a3b95c1b38bad5ed2cc5d`](https://github.com/rust-lang/rust/commit/25434f898b499876203a3b95c1b38bad5ed2cc5d) + +## Read-only view + +Zulip by default requires an account for interaction, though this "bug" is being +actively worked on by the Zulip developers. We currently maintain a read-only +view of the Zulip at ; this has relatively +up to date information (we update every 5 minutes). If you're linking to Zulip +from a GitHub comment with the intent to leave a permanent link, this is a good +place to link to. There is not currently good tooling for generating the links. diff --git a/src/platforms/zulip/moderation.md b/src/platforms/zulip/moderation.md new file mode 100644 index 000000000..fcb6f90c0 --- /dev/null +++ b/src/platforms/zulip/moderation.md @@ -0,0 +1,31 @@ +# Zulip Moderation + +Zulip, like all official Rust spaces, is governed by the [Code of +Conduct](https://www.rust-lang.org/policies/code-of-conduct). If you have +concerns, please feel free to escalate to the moderation team. + +However, though the moderation team is the top-level body here, it is not the +only place where you can seek help with moderation within Zulip. + +One method for reaching the Zulip administrators privately is to email +`zulip-admin.239bd484c0347d2d43214d8581f3e125.show-sender@streams.zulipchat.com`. +See [this page](https://rust-lang.zulipchat.com/help/message-a-stream-by-email) +for details on how this works. + +You can also ping the `@mods` group on Zulip; note that this will be public. + +It is not currently possible for normal users to self-administrate (e.g., muting +another user). However, each individual stream, including private streams, can +be muted: + +## For admins/moderators + +Some common actions for moderators are listed [on this +page](https://zulipchat.com/help/moderating-open-organizations). + +Notably, + * in ["Organization permissions"](https://rust-lang.zulipchat.com/#organization/organization-permissions) + we can restrict users to mandate invitations before joining (this is the "no new users" button) + +New admins/moderators should add themselves to the `mods` group on Zulip. (Note +that this is something that any user can do!) diff --git a/src/platforms/zulip/triagebot.md b/src/platforms/zulip/triagebot.md new file mode 100644 index 000000000..d992eb5e1 --- /dev/null +++ b/src/platforms/zulip/triagebot.md @@ -0,0 +1,223 @@ +# Triagebot + +Triaging on the rust-lang repository is an important step to take care of issues. The triagebot is the tool that allows *anyone* to help by assigning, self-assigning or labeling issues without being a member of the rust-lang organization. + +To enable triagebot on a particular repository (currently only in the rust-lang organization), add a `triagebot.toml` file in the repository root. It should have a section per "feature". Please read this page to learn how to enable each feature and the options supported; if you spot something missing please let us know [by filing an issue](https://github.com/rust-lang/rust-forge/issues), thanks! + +- [Issue assignment](#issue-assignment) +- [Issue notifications](#issue-notifications) +- [Ping a team](#ping-a-team) +- [Glacier](#glacier) +- [Triage](#triage) +- [Applying labels to issues](#applying-labels-to-issues) +- [Requesting prioritization](#requesting-prioritization) +- [Major Changes](#major-changes) + +## Issue assignment + +Any user belonging to the rust-lang organization can claim an issue via `@rustbot claim`. If the user is not part of the rust-lang organization `rustbot` will choose an assignee and add a "claimed" message in the top-level comment, to signal who the current assignee is. It is possible to override someone else's claim (no warning/error is given). + +You can drop your claim to the issue via `@rustbot release-assignment`; Rust team members can do the same if they want to release someone else's assignment. + +`@rustbot assign @user` can be used only by Rust team members and will assign that user to the issue (with same rules as before -- either directly or indirectly). + +Soon (when the "highfive" bot migration will be complete, see [rust-lang/highfive#258](https://github.com/rust-lang/highfive/pull/258)), `r?` will also assign reviewers to PRs, though unlike issues, non-team members cannot be assigned. Anyone can invoke the command. + +To enable on a repository, add the following to a triagebot.toml file in the repository root. + +```toml +[assign] +``` + +## Issue notifications + +Each registered team member has a notifications page at: + +`https://triagebot.infra.rust-lang.org/notifications?user=` + +This page is populated from direct mentions (@user) and team mentions (@rust-lang/libs) across the rust-lang organization. + +It can also be edited via Zulip by [private-messaging triagebot](https://rust-lang.zulipchat.com/#narrow/pm-with/261224-triage-rust-lang-bot). Any Rust organization member can edit their notifications page, or pages of other Rust organization team members. To do so, the editor must have a `zulip-id` listed in their people/username.toml file in the [team repository](https://github.com/rust-lang/team/). The bot will tell you which ID to use when talking to it for the first time; please `r? @Mark-Simulacrum` on PRs adding Zulip IDs. + +The following commands are supported: + + * `acknowledge ` + * `acknowledge ` + +These both acknowledge (and remove) a notification from the list. + + * `add ` + +This adds a new notification to the list. + + * `move ` + +This moves the notification at index `from` to the index `to`. + + * `meta ` + +This adds some text as a sub-bullet to the notification at `idx`. If the metadata is empty, the text is removed. + + * `as ` + +This executes any of the above commands as if you were the other GH user. + +## Ping a team + +The bot can be used to "ping" teams of people that do not have corresponding Github teams. This is useful because sometimes we want to keep groups of people that we can notify but we don't want to add all the members in those groups to the Github org, as that would imply that they are members of the Rust team (for example, Github would decorate their names with "member" and so forth). The compiler team uses this feature to reach the [notification groups](https://rustc-dev-guide.rust-lang.org/notification-groups/about.html). + +When a team is pinged, we will both post a message to the issue and add a label. The message will include a `cc` line that `@`-mentions all members of the team. + + +### Teams that can be pinged + +To be pinged, teams have to be created in the [Rust team repository](https://github.com/rust-lang/team). Frequently those teams will be marked as `marker-team`, meaning that they do not appear on the website. The [LLVM team](https://github.com/rust-lang/team/blob/master/teams/icebreakers-llvm.toml#L2) is an example. + +### Configuration + +To enable the team (e.g. `TeamName`) to be pinged, you have to add section to the `triagebot.toml` file at the root of a repository, like so: + +```toml +[ping.TeamName] +message = """\ +Put your message here. It will be added as a Github comment, +so it can include Markdown and other markup. +""" +label = "help wanted" +``` + +This configuration would post the given message and also add the label `help wanted` to the issue. + +You can also define aliases to add additional labels to refer to same target team. Aliases can be useful to add mnemonic labels or accomodate slight mispellings (such as "llvms" instead "llvm"), see the following example: + +```toml +[ping.cleanup-crew] +alias = ["llvm", "llvms"] +message = """\ +message content... +""" +``` + +Check out [the rust-lang/rust configuration](https://github.com/rust-lang/rust/blob/master/triagebot.toml) for an up-to-date examples. + + +### Pinging teams + +To ping the team `XXX`, simply leave a comment with the command: + +```text +@rustbot ping XXX +``` + +### Related issues + +* Requested in [https://github.com/rust-lang/triagebot/issues/169](https://github.com/rust-lang/triagebot/issues/169) + +## Glacier + +This adds the option to track ICEs (Internal Compiler Errors). Do note that the GitHub Gist must be from a [Rust Playground](https://play.rust-lang.org) link. The link must also be in quotes (`""`), example: + +`@rustbot glacier "https://gist.github.com/rust-play/xxx"` + +where `xxx` is the SHA1 hash of the GitHub gist generated by the Playground "share" button. + +## Triage + +This command can be used by people in charge of prioritizing issues, to assign either low or high priorities to issues. This is mostly done by the Compiler Prioritization WG for compiler bugs. + +`@rustbot triage {high,medium,low}` + +The configuration for this feature is: + +```toml +[triage] +remove = ["I-nominated"] # the set of labels to remove when this command is invoked +high = "P-high" +medium = "P-medium" +low = "P-low" +``` + +## Applying labels to issues + +Anyone can apply a label to issues. + +The specific grammar can be found [here](https://github.com/rust-lang/triagebot/blob/master/parser/src/command/relabel.rs), but some examples are listed below. The grammar is intended to be fairly intuitive for people, to prevent needing to reach for documentation when using the bot. + +```text +@rustbot modify labels to +T-lang, -T-compiler +``` + +This will remove the `T-compiler` label and add the `T-lang` label. You can also omit the `+` sign, if you want, and it'll be implied. + +You can also write the same command in a few other ways: + +```text +@rustbot modify labels to +T-lang and -T-compiler +@rustbot modify labels: +T-lang and -T-compiler +@rustbot modify labels to +T-lang and -T-compiler +``` + +Note that the command can either terminate with a `.` or a newline, otherwise the bot will not parse the command successfully. + +### Errors + +The bot currently restricts the labels that can be applied by people outside the Rust teams. For example, they can't add the I-unsound label. Most of the time, you shouldn't hit this. Feel free to ping the release team if you feel that a label should be added to the set of allowed labels! + +### Enabling +```toml +[relabel] +# any label is allowed to be set by team members (anyone on a team in rust-lang/team) +# but these can be set by anyone in the world +allow-unauthenticated = [ + "C-*", # any C- prefixed label will be allowed for anyone + # independent of authorization with rust-lang/team + "!C-bug", # but not C-bug (order does not matter) +] +``` + +## Requesting prioritization + +Users can request an issue to be prioritized by the Prioritization WG. + +To do so, you can invoke the following command: +```text +@rustbot prioritize +``` + +This will simply add the `I-prioritize` label to the issue. + +### Errors +The command fails if the issue has already been requested for prioritization (i.e. already has the `I-prioritize` label). + +### Enabling +```toml +[prioritize] +# Name of the label used for requesting prioritization on issues +label = "I-prioritize" +``` + +## Major Changes + +A major change is an issue that will have a big impact on users. See [this page on the MCP process](../../compiler/mcp.md) for detailed explanations. + +The compiler team uses the major change process, which requires: + * An issue + * A "second", who is an expert from the Compiler team who thinks the proposal is a good idea + +We have supporting automation for both parts. + +First, on the rust-lang/compiler-team repository, an issue with the "major-change" label (MCP = Major Change Proposal) is created via the template. Once that's opened, it automatically gains the "to-announce" label which should be removed when it's announced at a compiler team meeting. + +For seconds, you tell rustbot `@rustbot seconded` or `@rustbot second` and it will apply the relevant label. Only team members can do so. + +Configuration: +```toml +[major-change] +# Label to apply once an MCP is seconded +second_label = "final-comment-period" +# Label to apply when an MCP is created +meeting_label = "to-announce" +# The Zulip stream to automatically create topics about MCPs in +# Can be found by looking for the first number in URLs, e.g. https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler +zulip_stream = 131828 +``` From b1136057e3a11b755d5463f5fbf225343e71a205 Mon Sep 17 00:00:00 2001 From: apiraino Date: Sat, 27 Jun 2020 22:37:05 +0200 Subject: [PATCH 16/18] Apply more text fixes --- src/platforms/zulip/triagebot.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/platforms/zulip/triagebot.md b/src/platforms/zulip/triagebot.md index d992eb5e1..2eafcf47b 100644 --- a/src/platforms/zulip/triagebot.md +++ b/src/platforms/zulip/triagebot.md @@ -131,7 +131,7 @@ The configuration for this feature is: ```toml [triage] -remove = ["I-nominated"] # the set of labels to remove when this command is invoked +remove = ["I-prioritize"] # the set of labels to remove when this command is invoked high = "P-high" medium = "P-medium" low = "P-low" @@ -139,7 +139,7 @@ low = "P-low" ## Applying labels to issues -Anyone can apply a label to issues. +This command lets anyone apply labels to issues. This is most useful when opening an issue. In general, labels get applied to issues by the Triage WG. If you are interested in helping triaging issues, see the [Triage WG procedure](../../release/triage-procedure.md). The specific grammar can be found [here](https://github.com/rust-lang/triagebot/blob/master/parser/src/command/relabel.rs), but some examples are listed below. The grammar is intended to be fairly intuitive for people, to prevent needing to reach for documentation when using the bot. @@ -154,7 +154,7 @@ You can also write the same command in a few other ways: ```text @rustbot modify labels to +T-lang and -T-compiler @rustbot modify labels: +T-lang and -T-compiler -@rustbot modify labels to +T-lang and -T-compiler +@rustbot modify labels to +T-lang -T-compiler ``` Note that the command can either terminate with a `.` or a newline, otherwise the bot will not parse the command successfully. From 41237d739770c56c87a775c9fcc35f69e188ce10 Mon Sep 17 00:00:00 2001 From: apiraino Date: Sun, 28 Jun 2020 12:00:10 +0200 Subject: [PATCH 17/18] Document autolabel and notify_zulip triagebot commmands --- src/platforms/zulip/triagebot.md | 42 +++++++++++++++++++++++++++++--- 1 file changed, 38 insertions(+), 4 deletions(-) diff --git a/src/platforms/zulip/triagebot.md b/src/platforms/zulip/triagebot.md index 2eafcf47b..6f5977681 100644 --- a/src/platforms/zulip/triagebot.md +++ b/src/platforms/zulip/triagebot.md @@ -9,8 +9,10 @@ To enable triagebot on a particular repository (currently only in the rust-lang - [Ping a team](#ping-a-team) - [Glacier](#glacier) - [Triage](#triage) -- [Applying labels to issues](#applying-labels-to-issues) -- [Requesting prioritization](#requesting-prioritization) +- [Apply labels to issues](#apply-labels-to-issues) +- [Request prioritization](#request-prioritization) +- [Autolabel an issue](#autolabel-an-issue) +- [Notify Zulip](#notify-zulip) - [Major Changes](#major-changes) ## Issue assignment @@ -137,7 +139,7 @@ medium = "P-medium" low = "P-low" ``` -## Applying labels to issues +## Apply labels to issues This command lets anyone apply labels to issues. This is most useful when opening an issue. In general, labels get applied to issues by the Triage WG. If you are interested in helping triaging issues, see the [Triage WG procedure](../../release/triage-procedure.md). @@ -175,7 +177,7 @@ allow-unauthenticated = [ ] ``` -## Requesting prioritization +## Request prioritization Users can request an issue to be prioritized by the Prioritization WG. @@ -196,6 +198,38 @@ The command fails if the issue has already been requested for prioritization (i. label = "I-prioritize" ``` +## Autolabel an issue + +When certain labels are added to an issue, this command will trigger adding a set of additional prioritization labels to the issue. In the following example adding the "I-prioritize" label will automatically add the labels in `trigger_labels` but only if the issue is not already labeled with those in `exclude_labels` (this is to avoid applying unrelated labels to issues). + +```toml +[autolabel."I-prioritize"] +trigger_labels = [ + "regression-from-stable-to-stable", + "regression-from-stable-to-beta", + "regression-from-stable-to-nightly" +] +exclude_labels = [ + "P-*", + "T-infra", + "T-release" +] +``` + +## Notify Zulip + +When a prioritization label is added to an issue, this command will create a new topic on Zulip, in the designated stream: + +```toml +[notify-zulip."I-prioritize"] +zulip_stream = 245100 # t-compiler/wg-prioritization/alerts +topic = "I-prioritize #{number} {title}" +message_on_add = "@**WG-prioritization** issue #{number} has been requested for prioritization." +message_on_remove = "Issue #{number}'s prioritization request has been removed." +``` + +The subscribers of that Zulip stream will receive a notification and can discuss the prioritization of the issue. + ## Major Changes A major change is an issue that will have a big impact on users. See [this page on the MCP process](../../compiler/mcp.md) for detailed explanations. From 33b9967372a568052bcaaa81bfd97578ac8db10c Mon Sep 17 00:00:00 2001 From: apiraino Date: Mon, 29 Jun 2020 10:23:13 +0200 Subject: [PATCH 18/18] Clarify autolabel command template --- src/platforms/zulip/triagebot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/platforms/zulip/triagebot.md b/src/platforms/zulip/triagebot.md index 6f5977681..72e677265 100644 --- a/src/platforms/zulip/triagebot.md +++ b/src/platforms/zulip/triagebot.md @@ -218,7 +218,7 @@ exclude_labels = [ ## Notify Zulip -When a prioritization label is added to an issue, this command will create a new topic on Zulip, in the designated stream: +When a prioritization label is added to an issue, this command will create a new topic on Zulip, in the designated stream ("245100" in the following example), replacing `{number}` and `{title}` with the issue GitHub ID and title: ```toml [notify-zulip."I-prioritize"]