diff --git a/book.toml b/book.toml index 326c59bc1..c2bb437e5 100644 --- a/book.toml +++ b/book.toml @@ -13,6 +13,7 @@ command = "./build.bash" additional-js = ["js/moment.min.js", "js/index.js"] no-section-label=true git-repository-url="https://github.com/rust-lang/rust-forge" +curly-quotes = true [output.html.redirect] "beta-backporting.html" = "/release/backporting.html" @@ -48,3 +49,4 @@ git-repository-url="https://github.com/rust-lang/rust-forge" "chat/email.html" = "platforms/email.html" "chat/zulip/index.html" = "platforms/zulip/index.html" "chat/zulip.html" = "platforms/zulip.html" +"platforms/zulip/triagebot.html" = "/triagebot/index.html" diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 253eeb0d9..910318416 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -8,7 +8,30 @@ - [GitHub](./platforms/github.md) - [Zulip](./platforms/zulip.md) - [Moderation](./platforms/zulip/moderation.md) - - [Triagebot](./platforms/zulip/triagebot.md) +- [Triagebot](./triagebot/README.md) + - [Agenda Generator](./triagebot/agenda.md) + - [Issue Assignment](./triagebot/issue-assignment.md) + - [PR Assignment](./triagebot/pr-assignment.md) + - [Autolabels](./triagebot/autolabels.md) + - [Close](./triagebot/close.md) + - [Documentation Updates](./triagebot/doc-updates.md) + - [GitHub Releases](./triagebot/github-releases.md) + - [Glacier](./triagebot/glacier.md) + - [Labeling](./triagebot/labeling.md) + - [Major Changes](./triagebot/major-changes.md) + - [Mentions](./triagebot/mentions.md) + - [No Merge Policy](./triagebot/no-merge.md) + - [Nominate](./triagebot/nominate.md) + - [Note](./triagebot/note.md) + - [Notifications](./triagebot/notifications.md) + - [Pinging](./triagebot/pinging.md) + - [Requesting Prioritization](./triagebot/requesting-prioritization.md) + - [Review Changes Requested](./triagebot/review-submitted.md) + - [Rustc Commit Tracking](./triagebot/rustc-commit-list.md) + - [Shortcuts](./triagebot/shortcuts.md) + - [Triagebot Dashboard](./triagebot/triage-dashboard.md) + - [Zulip Meeting Management](./triagebot/zulip-meeting.md) + - [Zulip Notifications](./triagebot/zulip-notifications.md) - [Core](./core/README.md) - [Rust Blog Guidelines](./core/blogs.md) - [Community](./community/README.md) diff --git a/src/infra/service-infrastructure.md b/src/infra/service-infrastructure.md index e7e065a28..973a83860 100644 --- a/src/infra/service-infrastructure.md +++ b/src/infra/service-infrastructure.md @@ -48,8 +48,8 @@ Documentation on rfcbot commands can be found [rustbot](https://github.com/rust-lang/triagebot) is a bot ([bot user account](https://github.com/rustbot)) to assist with managing issues and PRs -to allow users to label and assign without GitHub permissions. See [the -wiki](https://github.com/rust-lang/triagebot/wiki) for more information. +to allow users to label and assign without GitHub permissions. See +[triagebot](../triagebot/index.html) for more information. ## DXR diff --git a/src/platforms/zulip/triagebot.md b/src/platforms/zulip/triagebot.md deleted file mode 100644 index 860757188..000000000 --- a/src/platforms/zulip/triagebot.md +++ /dev/null @@ -1,270 +0,0 @@ -# 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) -- [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 - -Any user belonging to the rust-lang organization can claim an issue via `@rustbot claim` or if the user is not part of the rust-lang organization `rustbot` will assign the issue to itself; then it will 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). - -The assignment handler also handles automatic assignment of PR reviewers and for the `r?` command to reassign reviewers. -See [the Assignment documentation](https://github.com/rust-lang/triagebot/wiki/Assignment) for more details. - -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://triage.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 ` (or short form `ack `) - * `acknowledge ` (or short form `ack `) - -These both acknowledge (and remove) a notification from the list. - - * `acknowledge all` or `acknowledge *` (or short form `ack all` or `ack *`) - -This acknowledges and removes all notifications. - - * `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 = ["cleanup", "cleanups", "shrink", "reduce", "bisect"] -message = """\ -message content... -""" -``` - -This will allow the command `@rustbot ping cleanup-crew` to be understood with all the aliased variants, ex.: - -```text -@rustbot ping cleanup -@rustbot ping shrink -... -``` - -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-prioritize"] # the set of labels to remove when this command is invoked -high = "P-high" -medium = "P-medium" -low = "P-low" -``` - -## 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). - -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 -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) -] -``` - -## Request 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" -``` - -## 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 ("245100" in the following example), replacing `{number}` and `{title}` with the issue GitHub ID and title: - -```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. - -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 -``` diff --git a/src/triagebot/README.md b/src/triagebot/README.md new file mode 100644 index 000000000..1e0d285f4 --- /dev/null +++ b/src/triagebot/README.md @@ -0,0 +1,77 @@ +# Triagebot + +Triagebot (AKA rustbot) is a general-purpose bot used for a wide variety of tasks in the rust-lang organization, usually involving sending commands via GitHub or Zulip comments. +The following pages explain the available features. + +Commands are usually issued by writing comments starting with the text `@rustbot`. +The commands that are available depends on which repository you are using. +Each repository has a `triagebot.toml` where you can see which features are enabled. + +For example, the following comment: + +```text +@rustbot label A-diagnostics A-macros +``` + +will set the given labels on a GitHub issue or pull request, even for people who don't have direct permissions to do that in the GitHub UI. + +## GitHub commands + +Commands on GitHub issues or pull requests are usually issued by writing `@rustbot` followed by the command anywhere in the comment. +`@rustbot` will ignore commands in markdown code blocks, inline code spans, or blockquotes. +Multiple rustbot commands can be entered in a single comment. + +Triagebot also allows editing of a comment. +If you don't modify the text of the command, then triagebot will ignore the edit. +However, if you modify an existing command, or add new ones, then those commands will be processed. + +## Configuration + +Individual GitHub repositories can configure triagebot features via a file called `triagebot.toml` in the root of the default branch. +The following pages explain the syntax needed for each feature. + +For example, the `rust-lang/rust` configuration file is at . + +When first adding `triagebot.toml` to a new repository, you will need to enable permissions for the bot to operate. +This can be done by posting a PR to the [`rust-lang/team`](https://github.com/rust-lang/team) database to add `bots = ["rustbot"]` to the repository in the `repos/rust-lang` directory. +Note that not all repositories are currently managed through the team database. +For those, reach out to the infrastructure team on the [`#t-infra`](https://rust-lang.zulipchat.com/#narrow/stream/242791-t-infra) Zulip stream to enable the relevant permissions for the automation on the repository. + +## Common command summary + +The following are some common commands you may see on [rust-lang/rust](https://github.com/rust-lang/rust/). + + + +| Command | Description | Docs | +|---------|-------------|------| +| `@rustbot claim` | Assigns an issue to yourself. | [Issue Assignment](issue-assignment.md) | +| `@rustbot release-assignment` | Removes your assignment to an issue. | [Issue Assignment](issue-assignment.md) | +| `@rustbot assign @octocat` | Assigns an issue to a specific user. | [Issue Assignment](issue-assignment.md) | +| `@rustbot ready` | Indicates a PR is ready for review. | [Shortcuts](shortcuts.md) | +| `@rustbot author` | Indicates a PR is waiting on the author. | [Shortcuts](shortcuts.md) | +| `@rustbot blocked` | Indicates a PR is blocked on something. | [Shortcuts](shortcuts.md) | +| `@rustbot label A-diagnostics A-macros` | Adds two labels to an issue or PR. | [Labeling](labeling.md) | +| `@rustbot label -P-high` | Removes a label from an issue or PR. | [Labeling](labeling.md) | +| `@rustbot ping windows` | Posts a comment pinging the Windows ping group. | [Pinging](pinging.md) | +| `@rustbot prioritize` | Requests prioritization from the Prioritization WG. | [Prioritization](requesting-prioritization.md) | +| `r? @octocat` | Assigns a PR to a user. | [PR Assignment](pr-assignment.md) | +| `r? libs` | Assigns to a random person in the libs review group. | [PR Assignment](pr-assignment.md) | +| `r? rust-lang/cargo` | Assigns a random person from the cargo team. | [PR Assignment](pr-assignment.md) | + +The following are some common commands you may see on Zulip: + +| Command | Description | Docs | +|---------|-------------|------| +| `@triagebot read` | Waits for people to read a document in a meeting. | [Zulip Meeting Management](zulip-meeting.md) | +| `@triagebot end-topic` | Checks if everyone is done discussing a topic in a meeting. | [Zulip Meeting Management](zulip-meeting.md) | +| `@triagebot end-meeting` | Checks if everyone is ready to finish a meeting. | [Zulip Meeting Management](zulip-meeting.md) | + +## Implementation + +The source code for triagebot can be found at . +If you are interested in extending triagebot, the documentation there should provide some guidance on how to get started. diff --git a/src/triagebot/agenda.md b/src/triagebot/agenda.md new file mode 100644 index 000000000..469918126 --- /dev/null +++ b/src/triagebot/agenda.md @@ -0,0 +1,15 @@ +# Agenda Generator + +The lang team uses the agenda generator to assist with meeting agendas. + +## Usage + +The agenda generator can be viewed at . + +## Configuration + +This feature has no configuration. + +## Implementation + +See [`src/agenda.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/agenda.rs). diff --git a/src/triagebot/autolabels.md b/src/triagebot/autolabels.md new file mode 100644 index 000000000..f9d5424e0 --- /dev/null +++ b/src/triagebot/autolabels.md @@ -0,0 +1,71 @@ +# Autolabels + +Auto labels will automatically apply labels to GitHub issues and PRs based on the `[autolabel]` configuration in `triagebot.toml`. + +## Usage + +Auto labels have no manual control. +See [labeling](labeling.md) for manually changing labels. + +## Configuration + +### Triggered by labels + +Labels can be added when another label is added. +The `trigger_labels` config option specifies which labels will cause this to trigger. + +```toml +# Automatically applies the `I-prioritize` label whenever one of the labels +# listed below is added to an issue (unless the issue already has one of the +# labels listed in `exclude_labels`). +[autolabel."I-prioritize"] +trigger_labels = [ + "regression-untriaged", + "regression-from-stable-to-stable", + "regression-from-stable-to-beta", + "regression-from-stable-to-nightly", + "I-unsound", +] +exclude_labels = [ + "P-*", + "T-infra", + "T-release", + "requires-nightly", +] +``` + +Exclude labels support shell-like `*` glob patterns. + +### Triggered by files + +Labels can be added based on which files are modified in a PR. +The `trigger_files` config option specifies which files will cause the label to be added. +Paths are matched with `starts_with`. + +```toml +# Adds the `T-compiler` label to any PR that touches `compiler` or +# `src/test/ui` unless it already has a `T-*` label. +[autolabel."T-compiler"] +trigger_files = [ + "compiler", + "tests/ui", +] +exclude_labels = [ + "T-*", +] +``` + +### Triggered by new PRs + +Labels can be added to any PR when it is opened. +Set the `new_pr = true` config option to enable this. +For example: + +```toml +[autolabel."S-waiting-on-review"] +new_pr = true +``` + +## Implementation + +See [`src/handlers/autolabel.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/handlers/autolabel.rs). diff --git a/src/triagebot/close.md b/src/triagebot/close.md new file mode 100644 index 000000000..2d1a53afb --- /dev/null +++ b/src/triagebot/close.md @@ -0,0 +1,26 @@ +# Close + +The close command can be used to close a GitHub issue or pull request. + +## Usage + +To close an issue or pull request, any rust-lang team member may enter the command: + +```text +@rustbot close +``` + +This will immediately close the issue or PR. + +## Configuration + +This feature is enabled on a repository by having a `[close]` table in `triagebot.toml`: + +```toml +[close] +``` + +## Implementation + +See [`src/handlers/close.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/handlers/close.rs) and +[`parser/src/command/close.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/parser/src/command/close.rs). diff --git a/src/triagebot/doc-updates.md b/src/triagebot/doc-updates.md new file mode 100644 index 000000000..c060d3b2f --- /dev/null +++ b/src/triagebot/doc-updates.md @@ -0,0 +1,13 @@ +# Documentation Updates + +Triagebot automatically generates a PR to [`rust-lang/rust`](https://github.com/rust-lang/rust/) every two weeks that updates all of the book submodules. +This PR requires manual approval. +These updates are currently managed by [`@ehuss`](https://github.com/ehuss/). + +## Usage + +There are no settings or manual controls for this feature. + +## Implementation + +See [`src/handlers/docs_update.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/handlers/docs_update.rs). diff --git a/src/triagebot/github-releases.md b/src/triagebot/github-releases.md new file mode 100644 index 000000000..de4c8befd --- /dev/null +++ b/src/triagebot/github-releases.md @@ -0,0 +1,39 @@ +# GitHub Releases + +Triagebot can be used to automatically create releases on GitHub when a tag is pushed, using the relevant section of the changelog as the release body. +No artifacts are uploaded when doing this. + +## Usage + +Any time you push a git tag, or update the contents of the changelog, triagebot will synchronize *all* tags with the releases. +That is, any tag that doesn't have a release will create a new release. +Additionally, the text of all the releases will be synchronized with the text in the changelog. + +Tags that don't have entries in the changelog will not create a release. + +## Configuration + +To enable automatically creating GitHub Releases, add this to the `triagebot.toml` at the root of your repository: + +```toml +[github-releases] +format = "rustc" +project-name = "Rust" +changelog-path = "RELEASES.md" +changelog-branch = "master" +``` + +The `format` defines which format the changelog file adheres to, and it's used to properly extract the relevant section from it. +You can add another format by changing triagebot's [`src/changelogs/`](https://github.com/rust-lang/triagebot/tree/master/src/changelogs). +The currently supported formats are: + +* `rustc`: follows the custom style of rustc's [RELEASES.md](https://github.com/rust-lang/rust/blob/master/RELEASES.md). + +The `project-name` defines what the title of the release should be. +The final title will be `{project-name} {tag}`. + +The `changelog-path` and `changelog-branch` keys define where triagebot should look at when searching for the changelog. + +## Implementation + +See [`src/handlers/github_releases.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/handlers/github_releases.rs) and [`src/changelogs/`](https://github.com/rust-lang/triagebot/tree/HEAD/src/changelogs). diff --git a/src/triagebot/glacier.md b/src/triagebot/glacier.md new file mode 100644 index 000000000..dd1054fe2 --- /dev/null +++ b/src/triagebot/glacier.md @@ -0,0 +1,27 @@ +# Glacier + +Triagebot can be used to automatically generate PRs on that contain code snippets that cause an ICE (Internal Compiler Error). + +## Usage + +Enter the code you want to post on the [Rust Playground](https://play.rust-lang.org). +Click the "Share" button and then copy the link for "Direct link to the gist". +Then post a comment on a GitHub issue with that link as: + +```text +@rustbot glacier "https://gist.github.com/rust-play/3d9134282f880c93bfe65e7db6b0680f" +``` + +Note that the link must be in double quotes. + +## Configuration + +This feature is enabled on a repository by having a `[glacier]` table in `triagebot.toml`: + +```toml +[glacier] +``` + +## Implementation + +See [`parser/src/command/glacier.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/parser/src/command/glacier.rs) and [`src/handlers/glacier.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/handlers/glacier.rs). diff --git a/src/triagebot/issue-assignment.md b/src/triagebot/issue-assignment.md new file mode 100644 index 000000000..460175ee2 --- /dev/null +++ b/src/triagebot/issue-assignment.md @@ -0,0 +1,29 @@ +# Issue Assignment + +The issue assignment commands allows any user to assign themselves to a GitHub issue. + +## Usage + +Issue assignment is done by entering one of these commands in a GitHub comment: + +* `@rustbot claim` --- Assigns the issue to yourself. +* `@rustbot release-assignment` --- Removes the current assignee. + Only the current assignee or a team member can release an assignment. +* `@rustbot assign @user` --- Assigns a specific user. + Only team members can assign other users. + +Due to GitHub restrictions, not all users can be directly assigned to an issue. +Only users with write permission to the repo, or rust-lang organization members can be directly assigned. +If triagebot is unable to directly assign the user, it will instead assign `@rustbot` and edit the top-level comment with a message that the issue has been claimed. + +## Configuration + +Issue assignment is enabled on a repository by the existence of the `[assign]` table in `triagebot.toml`: + +```toml +[assign] +``` + +## Implementation + +See [`parser/src/command/assign.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/parser/src/command/assign.rs) and [`src/handlers/assign.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/handlers/assign.rs). diff --git a/src/triagebot/labeling.md b/src/triagebot/labeling.md new file mode 100644 index 000000000..c76d0635e --- /dev/null +++ b/src/triagebot/labeling.md @@ -0,0 +1,80 @@ +# Labeling + +You can apply GitHub labels to an issue or PR by posting a comment. +Labeling of issues can be very helpful for searching, tying issues together, and indicating information in a formal way, such as the status. + +The Triage WG helps with labeling issues. +If you are interested in helping triaging issues, see the [Triage WG procedure](../release/triage-procedure.md). + +## Usage + +The general form of the comment should be `@rustbot label` followed by a space-separated list of labels to add or remove. +You can remove labels by prefixing them with the `-` character. +Some examples: + +* `@rustbot label A-diagnostics A-macros` +* `@rustbot label +T-lang -T-compiler` --- Removes `T-compiler` and adds `T-lang`. + +The syntax for the command is somewhat flexible, supporting a few different forms to suit your pleasure. +Some examples of variants you can use: + +* `@rustbot label: +T-lang, -T-compiler` +* `@rustbot label: +T-lang and -T-compiler` +* `@rustbot modify labels to +T-lang and -T-compiler` +* `@rustbot modify labels: +T-lang and -T-compiler` +* `@rustbot modify labels to +T-lang -T-compiler` + +The command can be terminated with a `.`, `;`, or the end of the line. + +Formally the grammar is: + +> Command → `@rustbot` `modify`? *label-word* `to`? `:`? *label-list* (`;` | `.`)? +> +> label-word →\ +>       `label`\ +>    | `labels` +> +> label-list →\ +>       *label-delta*\ +>    | *label-delta* `and` *label-list*\ +>    | *label-delta* `,` *label-list*\ +>    | *label-delta* `,` `and` *label-list* +> +> label-delta →\ +>       `+` *label*\ +>    | `-` *label*\ +>    | *label* +> +> label → \[^.,:!?;\n() ]+ + + +### Permissions + +All labels can be assigned by rust-lang organization team members (and wg-triage, wg-prioritization, and wg-async). +Users not on a team can only assign labels that are explicitly authorized in `triagebot.toml`. +It is encouraged for maintainers to allow the majority of labels to be applied by anyone. +An example of one that would be restricted is `beta-accepted`, since accepting a backport to beta is usually only done by a team member. + +## Configuration + +Labeling support is enabled on a repo by having a `[relabel]` table in `triagebot.toml`: + +```toml +[relabel] +``` + +Permissions for allowing unauthenticated labeling is done by listing the labels in the `allow-unauthenticated` list: + +```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) +] +``` + +## Implementation + +See [`src/handlers/autolabel.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/handlers/autolabel.rs). diff --git a/src/triagebot/major-changes.md b/src/triagebot/major-changes.md new file mode 100644 index 000000000..4fc924503 --- /dev/null +++ b/src/triagebot/major-changes.md @@ -0,0 +1,55 @@ +# Major Changes + +Triagebot helps with automated processing of [Major Change Proposals](../compiler/mcp.md). + +## Usage + +The process starts when the appropriate label is set on an issue. +For example, the [rust-lang/compiler-team] repo has a [major change template] which will automatically set the `major-change` label. +Triagebot will detect this and create a new Zulip topic for hosting discussion, and post a comment to the issue with a link to Zulip stream. + +If a team member writes a comment on the GitHub issue with `@rustbot second` (or `@rustbot seconded`), then triagebot will set the appropriate label, and post a comment to Zulip. + +If a team member adds the `major-change-accepted` label, then triagebot will post a comment to Zulip to let people know that it has been accepted. + +[rust-lang/compiler-team]: https://github.com/rust-lang/compiler-team/ +[major change template]: https://github.com/rust-lang/compiler-team/issues/new?assignees=&labels=major-change%2C+T-compiler&projects=&template=major_change.md&title=%28My+major+change+proposal%29 + +## Configuration + +This feature is enabled by the `[major-change]` table in `triagebot.toml`: + +```toml +[major-change] +# Issues that have this label will start the MCP process. +# Defaults to "major-change". +enabling_label = "major-change" + +# Label to apply once an MCP is seconded. +second_label = "final-comment-period" + +# Label to apply when an MCP is created. +# Typically this is used to track what needs to be discussed at a meeting. +meeting_label = "to-announce" + +# When this label is added to an issue, that triggers acceptance of the proposal +# which sends an update to Zulip. +# Defaults to "major-change-accepted". +accept_label = "major-change-accepted" + +# Optional extra text that is included in the GitHub comment when the issue is opened. +open_extra_text = "cc @rust-lang/compiler @rust-lang/compiler-contributors" + +# 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 = 233931 + +# An Zulip group or username to tag in the Zulip message when a +# proposal has been seconded. +zulip_ping = "T-compiler" +``` + +## Implementation + +See [`src/handlers/major_change.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/handlers/major_change.rs). diff --git a/src/triagebot/mentions.md b/src/triagebot/mentions.md new file mode 100644 index 000000000..1374a59ce --- /dev/null +++ b/src/triagebot/mentions.md @@ -0,0 +1,41 @@ +# Mentions + +Triagebot can leave a comment on PRs that touch certain files. +This can be useful to alert people who want to review any change to those files, or to provide a informational message to the author. + +## Usage + +Mentions are triggered automatically when a PR is opened (or new changes are pushed) based on the configuration in `triagebot.toml` of the repo. + +## Configuration + +To enable mentions, add entries to the `[mentions]` table in `triagebot.toml`. +Each key in the table should be a path in the repo. +Triagebot will check for modifications to any file that **starts with** the given path. +For example, `library/std` would match anything under the `library/std` directory like `library/std/src/process.rs`. + +There are two optional values that can be specified in the table: + +* `cc` --- A list of strings of users to ping. + They should start with `@` like `@ehuss` or `@rust-lang/clippy`. + If this is not specified, nobody will be pinged. +* `message` --- This is the message that will be included in the comment. + If this is not specified, the comment will say `Some changes occurred in {path}`. + +Example: + +```toml +[mentions."src/tools/cargo"] +cc = ["@ehuss"] + +[mentions."src/rustdoc-json-types"] +message = """ +rustdoc-json-types is a **public** (although nightly-only) API. +If possible, consider changing `src/librustdoc/json/conversions.rs`; +otherwise, make sure you bump the `FORMAT_VERSION` constant. +""" +``` + +## Implementation + +See [`parser/src/mentions.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/parser/src/mentions.rs) and [`src/handlers/mentions.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/handlers/mentions.rs) diff --git a/src/triagebot/no-merge.md b/src/triagebot/no-merge.md new file mode 100644 index 000000000..a99d741b2 --- /dev/null +++ b/src/triagebot/no-merge.md @@ -0,0 +1,24 @@ +# No Merge Policy + +The [no-merge policy] informs users if they have merge commits in their pull request. +Some repositories prefer to only use a rebase-oriented workflow. + +[no-merge policy]: https://rustc-dev-guide.rust-lang.org/git.html#keeping-things-up-to-date + +## Usage + +This is triggered automatically if a PR has merge commits. +Triagebot will post a comment on the PR if it detects merge commits. +The comment will explain the no-merge policy, and how the user can avoid merge commits. + +## Configuration + +This feature is enabled on a repository by having a `[no-merges]` table in `triagebot.toml`: + +```toml +[no-merges] +``` + +## Implementation + +See [`src/handlers/no_merges.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/handlers/no_merges.rs). diff --git a/src/triagebot/nominate.md b/src/triagebot/nominate.md new file mode 100644 index 000000000..7664006e6 --- /dev/null +++ b/src/triagebot/nominate.md @@ -0,0 +1,40 @@ +# Nominate + +The nominate commands are used for nominating issues for [backporting](../release/backporting.md). + +## Usage + +There are multiple commands that can be issued in a GitHub comment to handle nomination: + +* `@rustbot beta-nominate ` --- Adds the `beta-nominated` and the given team's label. + This indicates that the issue is nominated for beta backport, and the team should decide whether to accept or reject it. +* `@rustbot nominate ` --- Adds the `I-nominated` and the given team's label. + This is used to nominate an issue for the team to discuss. +* `@rustbot beta-accept` --- Adds the `beta-accepted` label. + This indicates that it has been approved for beta backport, and someone (usually the release team) will take care of applying the backport. + * `@rustbot beta-approve` --- An alias for `beta-accept`. + +Only rust-lang team members may use the nominate commands. + +Only teams that are listed in the [configuration](#configuration) can be nominated. + +If you need to nominate multiple teams, add each one in a separate command. +This is to encourage descriptions of what to do targeted at each team, rather than a general summary. + +## Configuration + +This feature is enabled on a repository by having a `[nominate]` table in `triagebot.toml`. +The `nominate.teams` table lists the team names, and the associated labels that should be used for that team. + +```toml +[nominate.teams] +compiler = "T-compiler" +release = "T-release" +core = "T-core" +infra = "T-infra" +``` + +## Implementation + +See [`src/handlers/nominate.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/handlers/nominate.rs) and +[`parser/src/command/nominate.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/parser/src/command/nominate.rs). diff --git a/src/triagebot/note.md b/src/triagebot/note.md new file mode 100644 index 000000000..f768184ab --- /dev/null +++ b/src/triagebot/note.md @@ -0,0 +1,63 @@ +# Note + +The `note` command can be used to update the top comment of a GitHub issue with a summary. + +## Usage + +A summary note can be added to a GitHub issue by writing a comment with the command: + +```text +@rustbot note summary-title +``` + +The word after `note` is then added as a link to the top comment of the GitHub issue: + +```markdown + + +### Summary Notes + +- ["summary-title" by @username](link-to-comment) + +Generated by triagebot, see [help](https://github.com/rust-lang/triagebot/wiki/Note) for how to add more + +``` + +with a link to the comment where you posted the `note` command. + +The title word can be a sequence of characters matching the regular expression `[^.,:!?;\n() ]+`. +Or it can be a quoted string like `"this is a title"`. + +Additional notes will get appended to the list: + +```markdown + + +### Summary Notes + +- ["first-note" by @username](link-to-comment) +- ["second-note" by @username](link-to-comment) +- ["summary-title" by @username](link-to-comment) + + +``` + +This summary section should **not** be edited by hand. + +### Removing an existing summary + +Notes can be removed by writing a comment with `@rustbot note remove summary-title`, +where `summary-title` is the word used when the note was created. +Triagebot will remove the entry from the summary list. + +## Configuration + +This feature is enabled by having a `[note]` table in `triagebot.toml`: + +```toml +[note] +``` + +## Implementation + +See [`parser/src/command/note.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/parser/src/command/note.rs) and [`src/handlers/note.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/handlers/note.rs). diff --git a/src/triagebot/notifications.md b/src/triagebot/notifications.md new file mode 100644 index 000000000..71f51f2b5 --- /dev/null +++ b/src/triagebot/notifications.md @@ -0,0 +1,53 @@ +# Notifications + +The notifications system helps a user keep track of GitHub notifications. + +## Usage + +Each registered team member has a notifications page at: + +`https://triage.rust-lang.org/notifications?user=` + +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). +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 ` (or short form `ack `) + * `acknowledge ` (or short form `ack `) + +These both acknowledge (and remove) a notification from the list. + + * `acknowledge all` or `acknowledge *` (or short form `ack all` or `ack *`) + +This acknowledges and removes all notifications. + + * `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 GitHub user. + +## Configuration + +There is no configuration for this feature. + +## Implementation + +See [`src/handlers/notification.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/handlers/notification.rs), +[`src/notification_listing.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/notification_listing.rs), and +[`src/db/notifications.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/db/notifications.rs). diff --git a/src/triagebot/pinging.md b/src/triagebot/pinging.md new file mode 100644 index 000000000..3f630f41c --- /dev/null +++ b/src/triagebot/pinging.md @@ -0,0 +1,68 @@ +# Pinging + +Triagebot 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. + +## Usage + +On repositories with a ping group configured, any Rust team member (and wg-triage, wg-prioritization, and wg-async) can write a GitHub comment such as: + +```text +@rustbot ping windows +``` + +which would cause triagebot to post a comment notifying the members of the `windows` ping group. + +### 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 [Icebreakers LLVM team](https://github.com/rust-lang/team/blob/master/teams/icebreakers-llvm.toml#L2) is an example. + +Additionally, the team needs to be configured in the repository's `triagebot.toml` file. + +## 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 accommodate slight misspellings (such as "llvms" instead "llvm"), see the following example: + +```toml +[ping.cleanup-crew] +alias = ["cleanup", "cleanups", "shrink", "reduce", "bisect"] +message = """\ +message content... +""" +``` + +This will allow the command `@rustbot ping cleanup-crew` to be understood with all the aliased variants, ex.: + +```text +@rustbot ping cleanup +@rustbot ping shrink +... +``` + +Check out [the rust-lang/rust configuration](https://github.com/rust-lang/rust/blob/master/triagebot.toml) for an up-to-date examples. + + +## Implementation + +See [`parser/src/command/ping.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/parser/src/command/ping.rs) and +[`src/handlers/ping.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/handlers/ping.rs). diff --git a/src/triagebot/pr-assignment.md b/src/triagebot/pr-assignment.md new file mode 100644 index 000000000..4bbaaa324 --- /dev/null +++ b/src/triagebot/pr-assignment.md @@ -0,0 +1,100 @@ +# PR Assignment + +Triagebot handles automatic and manual assignment of GitHub PRs. +It also handles welcoming new users when they post a PR. + +## Usage + +Automatic assignment of new PRs is handled by the configuration in the `triagebot.toml`, described [below](#configuration). + +Manual assignment can be done by posting a comment on the PR with the text: + +* `r? @octocat` --- Assigns a specific user. +* `r? octocat` --- The `@` is optional. +* `r? libs` --- Chooses a random person from the libs ad-hoc group defined in `triagebot.toml`. + For example, for the [rust-lang/rust] repository, see [`triagebot.toml`](https://github.com/rust-lang/rust/blob/master/triagebot.toml) for a list of ad-hoc group names. +* `r? rust-lang/libs` --- The `rust-lang/` org name prefix is optional. +* `r? rustdoc` --- Chooses a random person from the rustdoc team. + See the [teams database](https://github.com/rust-lang/team/tree/master/teams) for a list of team names. +* `r? rust-lang/rustdoc` --- The org name prefix is optional. + It is strongly recommended that you do not use `@`, as that will subscribe and notify the entire team to the PR. + +When choosing a user from a team, triagebot only looks at direct team members (it ignores subteams). + +When looking up a name, triagebot will first look at ad-hoc groups, then rust-lang teams, and if it doesn't match either of those it assumes it is a GitHub user. + +PRs can only be assigned to users with write permissions to the repo, any rust-lang org members with read permissions, or anyone who has commented on the PR. + +### Ghost + +Using `r? ghost` in the initial PR top-level comment when opening a PR will disable triagebot's auto-assignment. +`ghost` is GitHub's placeholder account for deleted accounts. +It is used here for convenience. +This is typically used for rollups or experiments where you don't want any assignments or noise. + +## Configuration + +PR assignment is enabled on the repository by having an `[assign.owners]` table in `triagebot.toml`: + +```toml +# These are ad-hoc groups that can be referenced in `r?` and the `owners` table below. +# The values may contain GitHub usernames, other groups, or rust-lang teams. +# The `@` is optional. +# Group names should be lowercase. +[assign.adhoc_groups] +libs = ["@joshtriplett", "@Mark-Simulacrum", "@kenntytm", "@m-ou-se", "@thomcc"] +# Can reference other groups. +compiler = ["compiler-team", "compiler-team-contributors"] +compiler-team = ["cjgillot", "estebank"] +compiler-team-contributors = ["compiler-errors", "jackh726"] +# Can reference rust-lang teams. +libs = ["rust-lang/libs-api"] +# This is a special group that will be used if none of the `owners` entries matches. +fallback = ["@Mark-Simulacrum"] + +# This specifies users, groups, or teams to assign for different paths. +# Triagebot will pick one person to assign. +# Paths are gitignore-style matches. +[assign.owners] +# Examples of assigning individuals. +"Cargo.lock" = ["@Mark-Simulacrum"] +"/library/std/src/sys/windows" = ["@ChrisDenton"] +# Example of assigning to a group. +"/library/std" = ["libs"] +# Supports gitignore patterns. +"*.js" = ["@octocat"] +# If you want to match all files, `*` should be sufficient. +"*" = ["@octocat"] +# Can use teams from the rust-lang teams database. +"/src/tools/cargo" = ["@rust-lang/cargo"] +``` + +If the `owners` map is configured, then triagebot will automatically select a reviewer based on which files were modified in the PR. +The existence of the owners table also enables the ability for users to post a comment with `r? name` to set the assignment to a specific user. + +### Additional new PR trigger options + +Triagebot will also post a welcome message to the user. +Its behavior depends on a few factors: + +* PR authors who have not previously made any commits will get a more detailed welcome message. +* PR authors who have made commits will get an abbreviated message. +* If the initial PR comment has an `r?` command, then no welcome will be posted. + +There are several options in `triagebot.toml` for controlling its behavior on new PRs: + +```toml +[assign] +# If set, posts a warning message if the PR is opened against a non-default +# branch (usually main or master). +warn_non_default_branch = true +# If set, the welcome message to new contributors will include this link to +# a contributing guide. +contributing_url = "https://rustc-dev-guide.rust-lang.org/contributing.html" +``` + +Additionally, triagebot will post a comment with a warning if the PR modifies any submodules. + +## Implementation + +See [`parser/src/command/assign.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/parser/src/command/assign.rs) and [`src/handlers/assign.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/handlers/assign.rs). diff --git a/src/triagebot/requesting-prioritization.md b/src/triagebot/requesting-prioritization.md new file mode 100644 index 000000000..367f94b2c --- /dev/null +++ b/src/triagebot/requesting-prioritization.md @@ -0,0 +1,30 @@ +# Requesting Prioritization + +Users can request an issue to be prioritized by the Prioritization WG. + +## Usage + +On repositories configured for prioritization, any user can post a comment with: + +```text +@rustbot prioritize +``` + +which will add the `I-prioritize` label to the issue to notify the [Prioritization WG] that the issue needs prioritization. + +[Prioritization WG]: https://www.rust-lang.org/governance/teams/compiler#Prioritization%20working%20group + +## Configuration + +This feature is enabled on a repository by the `[prioritize]` table in `triagebot.toml`: + +```toml +[prioritize] +# Name of the label used for requesting prioritization on issues +label = "I-prioritize" +``` + +## Implementation + +See [`parser/src/command/prioritize.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/parser/src/command/prioritize.rs) and +[`src/handlers/prioritize.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/handlers/prioritize.rs). diff --git a/src/triagebot/review-submitted.md b/src/triagebot/review-submitted.md new file mode 100644 index 000000000..a673e0181 --- /dev/null +++ b/src/triagebot/review-submitted.md @@ -0,0 +1,24 @@ +# Review Changes Requested + +This feature will automatically adjust the labels on a pull request when a reviewer sends a review with changes requested. + +## Usage + +When creating a pull request review, click the "Request Changes" option when finishing the review. +This will automatically remove the review labels, and add a new label to indicate that the PR is waiting on the author. + +## Configuration + +This feature is enabled on a repository by having a `[review-submitted]` table in `triagebot.toml`: + +```toml +[review-submitted] +# These labels are removed when a review is submitted. +review_labels = ["S-waiting-on-review"] +# This label is added when a review is submitted. +reviewed_label = ["S-waiting-on-author"] +``` + +## Implementation + +See [`src/handlers/review_submitted.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/handlers/review_submitted.rs). diff --git a/src/triagebot/rustc-commit-list.md b/src/triagebot/rustc-commit-list.md new file mode 100644 index 000000000..f773a5376 --- /dev/null +++ b/src/triagebot/rustc-commit-list.md @@ -0,0 +1,18 @@ +# Rustc Commit Tracking + +Triagebot keeps a database of commits to the [`rust-lang/rust`](https://github.com/rust-lang/rust/) repository. +This is useful since the GitHub API for fetching this information can be slow. +For example, this is used by the [rustc-perf](https://github.com/rust-lang/rustc-perf) system. + +## Usage + +The top-level bors merge commits can be fetched from . + +## Configuration + +This has no configuration, it is processed automatically. + +## Implementation + +See [`src/db/rustc_commits.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/db/rustc_commits.rs) and +[`src/handlers/rustc_commits.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/handlers/rustc_commits.rs). diff --git a/src/triagebot/shortcuts.md b/src/triagebot/shortcuts.md new file mode 100644 index 000000000..7d6edaaea --- /dev/null +++ b/src/triagebot/shortcuts.md @@ -0,0 +1,43 @@ +# Shortcuts + +Shortcuts are simple commands for performing common tasks. + +## Usage + +Shortcut commands can be issued by writing a GitHub comment as indicated below. + +### ready + +`@rustbot ready` + +This indicates that a PR is ready for review. +This assigns the `S-waiting-on-review` label on the pull request and removes both `S-waiting-on-author` and `S-blocked` if present. + +`@rustbot review` or `@rustbot reviewer` are aliases for `ready`. + +### author + +`@rustbot author` + +This indicates that a PR is waiting on the author. +This assigns the `S-waiting-on-author` label on the pull request and removes both `S-waiting-on-review` and `S-blocked` if present. + +### blocked + +`@rustbot blocked` + +This indicates that a PR is blocked on something. +This assigns the `S-blocked` label on the pull request and removes both `S-waiting-on-author` and `S-waiting-on-review` if present. + +## Configuration + +This feature is enabled on a repository by having a `[shortcut]` table in `triagebot.toml`: + +```toml +[shortcut] +``` + +## Implementation + +See [`parser/src/command/shortcut.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/parser/src/command/shortcut.rs) and +[`src/handlers/shortcut.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/handlers/shortcut.rs). diff --git a/src/triagebot/triage-dashboard.md b/src/triagebot/triage-dashboard.md new file mode 100644 index 000000000..65202be94 --- /dev/null +++ b/src/triagebot/triage-dashboard.md @@ -0,0 +1,17 @@ +# Triagebot Dashboard + +The triage dashboard is used to assist with triaging open pull requests. + +## Usage + +The triage dashboard for repositories can be found at . + +Any rust-lang repository can be viewed with the form `https://triage.rust-lang.org/triage//`. + +## Configuration + +This feature has no configuration. + +## Implementation + +See [`src/triage.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/triage.rs). diff --git a/src/triagebot/zulip-meeting.md b/src/triagebot/zulip-meeting.md new file mode 100644 index 000000000..bfa260554 --- /dev/null +++ b/src/triagebot/zulip-meeting.md @@ -0,0 +1,68 @@ +# Zulip Meeting Management + +Triagebot can respond to some commands in Zulip to assist with running a meeting. + +## Usage + +Enter a message in Zulip addressed to `@triagebot` with a command listed below. + +### Document reading + +```text +@triagebot read +``` + +This command will cause triagebot to post a comment to poll when everyone is finished reading some document, and are ready to start discussing it. +The message looks something like: + +```text +Click on the :book: when you start reading (and leave it clicked). +Click on the :checkered_flag: when you finish reading. +``` + +Users can then click the emoji reaction buttons to indicate that they are currently reading, and then again when they are finished. + +### End topic + +```text +@triagebot end-topic +``` + +This command will cause triagebot to post a comment to poll if everyone in the meeting is ready to move on to the next topic. +The message looks something like: + +```text +Does anyone have something to add on the current topic? +React with :working_on_it: if you have something to say. +React with :all_good: if not. +``` + +Users can then click the emoji reaction buttons to indicate if they are ready or not. + +`@triagebot await` is an alias for `end-topic`. + +### End meeting + +```text +@triagebot end-meeting +``` + +This command will cause triagebot to post a comment to poll if everyone is ready to end the meeting. +The message looks something like: + +```text +Does anyone have something to bring up? +React with :working_on_it: if you have something to say. +React with :all_good: if you're ready to end the meeting. +``` + +Users can then click the emoji reaction buttons to indicate if they are ready to end or not. + +## Configuration + +This feature has no configuration, it is available to all team members. +Note that your Zulip ID needs to be configured in the [teams database](https://github.com/rust-lang/team). + +## Implementation + +See [`src/zulip.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/zulip.rs). diff --git a/src/triagebot/zulip-notifications.md b/src/triagebot/zulip-notifications.md new file mode 100644 index 000000000..46d9b70ce --- /dev/null +++ b/src/triagebot/zulip-notifications.md @@ -0,0 +1,54 @@ +# Zulip Notifications + +Triagebot can send messages to Zulip based on various triggers like issue labels. + +## Usage + +Zulip notifications are automated based on the configuration described below. +They can be triggered based on the addition or removal of labels, or when an issue is closed or reopened. + +For example, the `rust-lang/rust` repository is configured to automatically post a message whenever an issue is tagged with the `A-edition-2021` label to the "Edition 2021" stream, which looks something like: + +> triagebot +> +> Issue [#109298](https://github.com/rust-lang/rust/issues/109298) "ICE `Subslice unexpected because it isn't captured` --edition=2021" has been added. + +## Configuration + +This feature is enabled on a repository by having a `[notify-zulip]` table in `triagebot.toml`: + +```toml +# Triggers a Zulip notification based on the given label name. +[notify-zulip."label-name"] +# The Zulip stream to post to. +# 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 = 245100 # #t-compiler/wg-prioritization/alerts + +# The Zulip topic to post to. +# {number} is replaced with the issue/PR number. +# {title} is replaced with the issue/PR title. +topic = "#{number} {title}" + +# The message to post when the label is added. +# Supports {number} and {title} substitution. +message_on_add = "Issue #{number} \"{title}\" has been added." + +# The message to post when the label is removed. +# Supports {number} and {title} substitution. +message_on_remove = "Issue #{number}'s nomination has been removed. Thanks all for participating!" + +# The message to post when the issue/PR is closed and it has the label. +# Supports {number} and {title} substitution. +message_on_close = "Issue #{number} has been closed. Thanks for participating!" + +# The message to post when the issue/PR is reopened and it has the label. +# Supports {number} and {title} substitution. +message_on_reopen = "Issue #{number} has been reopened. Pinging @*T-types*." + +# The Zulip notification will not be posted unless the issue/PR has all of these labels. +required_labels = ["I-nominated"] +``` + +## Implementation + +See [`src/handlers/notify_zulip.rs`](https://github.com/rust-lang/triagebot/blob/HEAD/src/handlers/notify_zulip.rs).