Set up automatic notifications for SMEs with Qiskit Bot

[Eric-Arellano]

We discussed either using Qiskit Bot or GitHub code owners so that SMEs (subject matter experts) are aware of when changes are proposed to docs that they're an expert on.

Update Sept 12, 2023: Some notes from a meeting with the Qiskit devs about this.

• Matthew T: codeowners shouldn't be used solely for notifications. It's more about permissions of who actually does own the file. Otherwise, use Qiskit Bot
• Jake: does not like Qiskit Bot with explicit @s because it's the highest level of notification (mention). He prefers being added as a normal PR review
• Eric A. (me): concerned about automatic notifications being noisy for PRs that don't need SMEs, like typo fixes. Instead, we should make it easy for technical writers to know who the SMEs are, but we manually ask them for review

I think likely the best approach is to use Qiskit bot, but with escaped usernames using `. That will add a comment to PRs that makes clear who the relevant SMEs are, and then the author can manually tag those SMEs for a review when ready.

[Eric-Arellano]

We finalized the plan: use Qiskit bot with escaped handles. That allows docs authors to know who the relevant SMEs are so that they can manually ping them for review. We escape the usernames so that we don't bother SMEs with things they don't need to look at, like fixing typos.

@javabster will come up with the file mapping. I will add Qiskit bot to this repo.

[Eric-Arellano]

@javabster post-Summit, do we still want to do this?

[javabster]

@Eric-Arellano yes, I think we should still do this, and start building it into our contributing process any time there is a brand new page added

[Eric-Arellano]

We decided to use the Qiskit Bot for notifications. Abby M mapped the SMEs to files at https://ibm.ent.box.com/notes/1393006419882.

We want this specific functionality:

The other main feature the bot offers is to automatically leave a message on all new PRs when they are opened. This can be useful to leave a comment to set expectations for contributors but also be used to notify particular people to review the PR. The bot is configurable for each project so that subsets of github users can be mentioned in this comment automatically based on the files changed in the PR.

You'll need to set up qiskit_bot.yaml in the root of the repository and set notifications, always_notify to true, and notification_prelude to:

Thanks for contributing to Qiskit documentation!

Before your PR can be merged, it will first need to pass continuous
integration tests and be reviewed. Sometimes the review process can be slow,
so please be patient.

You also need to set up webhooks in GitHub's config for the repository at https://github.com/Qiskit/documentation/settings/hooks:

The last piece of github side configuration needed is to configure the webhook. You need to configure a webhook for each repository that uses the bot. Setup the webhook to send all necessary event types to the endpoint where the bot is running. Two things to remember is that make sure you send the webhook events to the /postreceive endpoint off of the server's address and that the Content type is set to application/json.

[Eric-Arellano]

Closed by #867 and @arnaucasau's prior work. Thank you both, and thanks @javabster for the mapping of files to maintainers!