Merge pull request #877 from Kobzol/zulip-commands

Document Zulip commands

Author: ehuss

src/SUMMARY.md

@@ -42,6 +42,7 @@
     - [Rustc Commit Tracking](./triagebot/rustc-commit-list.md)
     - [Shortcuts](./triagebot/shortcuts.md)
     - [Triagebot Dashboard](./triagebot/triage-dashboard.md)
+    - [Zulip Commands](./triagebot/zulip-commands.md)
     - [Zulip Meeting Management](./triagebot/zulip-meeting.md)
     - [Zulip Notifications](./triagebot/zulip-notifications.md)
     - [GitHub Actions created PR open/closer](./triagebot/bot-pull-requests.md)

src/triagebot/notifications.md

@@ -10,7 +10,7 @@ Each registered team member has a notifications page at:
 
 Whenever you are mentioned on GitHub with a direct mention (`@user`) or via a team mention (`@rust-lang/libs`) anywhere in the rust-lang organization, this will add an entry to the notifications list.
 
-The notifications list can also be edited via Zulip by [private-messaging triagebot](https://rust-lang.zulipchat.com/#narrow/pm-with/261224-triage-rust-lang-bot).
+The notifications list can also be edited via Zulip by [private-messaging triagebot](zulip-commands.md#direct-message-commands).
 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.
@@ -38,10 +38,6 @@ This moves the notification at index `from` to the index `to`.
 
 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 GitHub user.
-
 ## Configuration
 
 There is no configuration for this feature.

src/triagebot/review-queue-tracking.md

@@ -37,24 +37,11 @@ Note that the review preferences only affect assignment based on adhoc groups or
 
 ## Usage
 
-You can examine your review queue and configure your review preferences by sending a DM (Direct Message) to the `triagebot` bot account on the [Zulip chat](../platforms/zulip.md). You can open a DM session with the `triagebot` bot by clicking on [this link](https://rust-lang.zulipchat.com/#narrow/dm/261224-triagebot) (requires Zulip login).
+You can examine your review queue and configure your review preferences by sending a [Direct Message command](zulip-commands.md#direct-message-commands) to `triagebot`:
 
-You can send a message with one of these commands to `triagebot`:
-
-- `work help` --- Show the available commands.
-- `work show` --- Show the contents of your review queue (in the `rust-lang/rust` repository) and your review preferences.
-- `work set-pr-limit <number>|unlimited` --- Set your review capacity to `<number>` or remove the capacity limit (`unlimited`).
-- `work set-rotation-mode off|on` --- Set your rotation mode to be `on` or `off`.
-
-You can also run the above commands on behalf of other GitHub users with the following message:
-
-```
-as <github-username> <command>
-# e.g.
-as MyFavouriteGitHubUser work show
-```
-
-`triagebot` will notify the user that you have executed a command on their behalf. Note that this functionality is intended for rare occasions or debugging, please do not use it often.
+- `work show`: Show the contents of your review queue (in the `rust-lang/rust` repository) and your review preferences.
+- `work set-pr-limit <number>|unlimited`: Set your review capacity to `<number>` or remove the capacity limit (`unlimited`).
+- `work set-rotation-mode off|on`: Set your rotation mode to be `on` or `off`.
 
 ## Implementation
 

src/triagebot/zulip-commands.md

@@ -0,0 +1,48 @@
+# Triagebot Zulip commands
+
+You can send commands to triagebot on the [Rust Zulip](https://rust-lang.zulipchat.com) server using two separate mechanisms:
+
+- Sending a direct message (DM) to the [triagebot][triagebot-dm] account.
+- Sending a message in some stream by tagging `@triagebot`, followed by a command (e.g. `@triagebot end-meeting`).
+
+Triagebot commands can only be sent by users that are in the [team](https://github.com/rust-lang/team) database.
+
+## Direct message commands
+
+You can send these commands as a direct message to the [triagebot][triagebot-dm] account.
+
+- `whoami`: shows the Rust teams that you are a part of
+- `lookup github <zulip-name>`: lookup the GitHub username of a user by their Zulip name
+- `lookup zulip <github-username>`: lookup the Zulip name of a user by their GitHub username
+- `team-stats <team-name>`: show the review workqueue statistics of all members of the given team
+- Reviewer workqueue commands, which are documented [here](review-queue-tracking.md#usage).
+- Notification commands, which are documented [here](notifications.md#usage).
+
+You can use the `--help` flag or a `help` subcommand for any of these commands to find out more about their parameters.
+
+### Impersonation
+
+You can also run the above commands on behalf of other GitHub users with the following message:
+
+```text
+as <github-username> <command>
+# e.g.
+as MyFavouriteGitHubUser work show
+```
+
+If you execute a "sensitive" command in this way (i.e. a command that modifies something), `triagebot` will notify the user that you have impersonated via a direct message.
+
+Note that the impersonation functionality is intended for inspecting the status (e.g. the reviewer workqueue or Rust teams) of other users or occasional debugging. Please do not use it maliciously.
+
+## Stream commands
+
+- *Meeting* commands serve for controlling the flow of Zulip meetings. They are documented [here](zulip-meeting.md).
+- *Rust Project Goals* commands serve for controlling Rust Project Goal tracking.
+  - `@triagebot ping-goals <threshold> <next-update>`: For use by the goals team to ping goal owners on Zulip to give an update on their goal. Will not ping if there has been a comment in `<threshold>` days. `<next-update>` is a string to say when the next blog update will start.
+- `@triagebot docs-update`: Generates a Pull Request ([example](https://github.com/rust-lang/rust/pull/141923)) to update the documentation submodules. See [Documentation Updates](doc-updates.md).
+
+## Implementation
+
+See [`src/zulip.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/zulip.rs).
+
+[triagebot-dm]: https://rust-lang.zulipchat.com/#narrow/dm/261224-triagebot