Add Triagebot documentation

[apiraino]

Superseded by #394

---

Hi,

this PR would like to help moving the Triagebot documentation (currently hosted on the bot's repo Wiki) to the rust-forge as per the discussion during the Steering Meeting of 2020-06-23.

The triagebot wiki is structured as a multi-file hierarchy, which I find to be a bit too fragmented for an already long document such as this one, so the main change I thought is to compress everything in a single page (kind of a man 1 triagebot).

I've also slightly reworded and disentangled some parts, as I felt they might more approachable for a newcomer (which I am, so maybe my perspective could help a little bit), therefore this document is not a bare copypaste of the original Wiki.

Some points that will need some attention:

• Some TODOs (will comment each of them)
• I guess that I can replace all occurrencies of @rustbot with @triagebot, is that correct?
• Other piece of documentation to maybe merge into this PR?

This proposal is quite raw and I expect to iterate a couple of times to refine details and remove all inaccuracies.

Thanks everyone for helping me improving on this!

cc @spastorino

[apiraino]

left some comments, looking forward to receiving comments 👍

[XAMPPRocky]

Thank you for your PR! cc @Mark-Simulacrum @LeSeulArtichaut @Elinvynia

[LeSeulArtichaut]

Thanks a lot for doing this work @apiraino! I've left as many comment as I could.

One thing that I think is missing right now, is "where are commands valid?". Some commands can only be used on GitHub, some can only be used on Zulip. I think we should absolutely document that. Also, this makes me think: do we want this file in the chat/zulip folder, where the bot is primarely meant as a GitHub tool, and only recently got uses on Zulip?

Also, I recently split the prioritize commands into smaller bits, see rust-lang/triagebot#616. However I didn't write documentation for it, this is my bad. Please tell me if you want to write it or if you prefer to delegate that to me.
Basically, instead of a big feature that's specialized for prioritization as performed by our Prioritization WG, there is now 3 different features that are much more flexible.

• An "autolabel" feature, that automatically adds more labels when specific labels are added. This is used e.g. to add I-prioritize when an issue is labeled as I-unsound.
• A "notify-zulip" feature, that creates a topic on Zulip when specific labels are added. This is used to create all the different topics that we use for the WG.
• The "prioritization" command itself, that only adds the I-prioritize label, and does nothing else. However, the event of the label being added is caught by the "notify-zulip" handler which then creates the Zulip topic.

I hope that this explanation makes things more clear. Please ping me if you want me to write the configuration for this, or if you have more unresolved questions.

[LeSeulArtichaut]

Again, this "ICE-breaker" term should be removed.

[apiraino]

ok, names updated. I see that for now the rust-lang team files seem to keep the old label of "ICE-breakers". I guess at some point this 'icebreakers' thing will disappear from there, too.

[LeSeulArtichaut]

I’m unsure what’s the exact status for this. cc @nikomatsakis

[nikomatsakis]

yeah it's out of date. I'll update the team files I guess.

[nikomatsakis]

though we did already :)

[LeSeulArtichaut]

I guess that I can replace all occurrencies of @rustbot with @triagebot, is that correct?

The bot is named @rustbot on GitHub and @triagebot on Zulip. This is also why we absolutely need to have explanations on what the bot can and cannot do on each platform.

[apiraino]

@XAMPPRocky @LeSeulArtichaut fantastic review, thanks! I will go over it and tick these items off (for some of them I'll likely need a few more directions)

[apiraino]

I guess that I can replace all occurrencies of @rustbot with @triagebot, is that correct?

The bot is named @rustbot on GitHub and @triagebot on Zulip. This is also why we absolutely need to have explanations on what the bot can and cannot do on each platform.

@LeSeulArtichaut After some thought, I'm not sure how, I'll search for more documentation. I agree to document all triagebot things here, though (as you suggested).
By the way, when I searched info about the GitHub rustbot I've automatically opened the GitHub section of this document, which might be the wrong reflex, but it signaled me how I felt about documenting the GitHub rustbot.

[XAMPPRocky]

@apiraino I think we can also move the GitHub section under platforms, and we can have a another subpage under it for bot commands on GitHub. I was thinking of moving it after we merged this anyway.

[apiraino]

One thing that I think is missing right now, is "where are commands valid?". Some commands can only be used on GitHub, some can only be used on Zulip. I think we should absolutely document that. Also, this makes me think: do we want this file in the chat/zulip folder, where the bot is primarely meant as a GitHub tool, and only recently got uses on Zulip?

@LeSeulArtichaut I have now rearranged the documentation under the "Platforms" chapter so it's starting to shape like you and @XAMPPRocky are suggesting. Currently I'm not able to properly document these bots so I'd suggest moving this to a subsequent PR iterating over this one (I'll be happy to help with your guidance).

Also, I recently split the prioritize commands into smaller bits, see rust-lang/triagebot#616. However I didn't write documentation for it, please tell me if you want to write it or if you prefer to delegate that to me.

I gathered a bit of knowledge from the issue comments and had a look at the code. I tried giving some contexts for these new commands in 41237d7 but my wording might be a bit "hand-wavy" so please feel free to comment on that.

After this, I think it could be the right time to rebase this PR and clean it up a bit for a second review