Add Triagebot documentation

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"

src/SUMMARY.md

@@ -1,11 +1,13 @@
 # Rust Forge
 
 [Overview](./README.md)
-- [Chat Platforms](./chat/README.md)
-  - [Discord](./chat/discord.md)
-  - [Email](./chat/email.md)
-  - [Zulip](./chat/zulip.md)
-      - [Moderation](./chat/zulip/moderation.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)
@@ -31,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)

src/chat/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=<gh-username>`
+
+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 <url>`
+ * `acknowledge <idx>`
+
+These both acknowledge (and remove) a notification from the list.
+
+ * `add <url> <description... (multiple words)>`
+
+This adds a new notification to the list.
+
+ * `move <from> <to>`
+
+This moves the notification at index `from` to the index `to`.
+
+ * `meta <idx> <metadata...>`
+
+This adds some text as a sub-bullet to the notification at `idx`. If the metadata is empty, the text is removed.
+
+ * `as <github username> <command...>`
+
+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:
+
+```
+[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:
+
+```
+[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:
+
+```
+@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.
+
+```
+@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 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
+```

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.

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 <br/>
+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 <br/>
+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 <br/>
+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. 
+
+
+

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. `[email protected]`.
+
+## 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