Clarify wording of notification reviewer list (#44)

* Clarify wording of notification reviewer list * Fix double "the" Co-authored-by: Arnau Casau <47946624+arnaucasau@users.noreply.github.com> --------- Co-authored-by: Arnau Casau <47946624+arnaucasau@users.noreply.github.com>
Qiskit · May 16, 2024 · 4f5fdd4 · 4f5fdd4
1 parent 3441614
commit 4f5fdd4
Show file tree

Hide file tree

Showing 3 changed files with 40 additions and 41 deletions.
diff --git a/README.md b/README.md
@@ -1,51 +1,47 @@
 # qiskit-bot
 
-This repo contains a wsgi app for running for github automation of the 
-qiskit organization. It performs many functions to automate the workflow of the
-various aspect of managing the repositories in the qiskit github organization.
-For example, release automation to automatically generate a github release with
+This repo contains a wsgi app for running for GitHub automation of the 
+Qiskit organization. It performs many functions to automate the workflow of the
+various aspect of managing the repositories in the Qiskit GitHub organization.
+For example, release automation to automatically generate a GitHub release with
 a full changelog from just a git tag and then generate a PR to bump the
 meta-repository based on that tag. The goal of this project is to minimize the
 number of manual actions needed as part of daily maintenance of qiskit.
 
 As of right now the bot concentrates on release process automation. It handles
 3 key aspects of that. First it generates release notes based on the git log
-and pull request tags. This generated changelog is added to the github releases
+and pull request tags. This generated changelog is added to the GitHub releases
 page. The next step is branch creation. If a project is configured to branch
-on minor releases the bot will automatically create the branch. The last step
-is bumping the meta repository to include the new version of the released
-element. This will handle increasing the meta-package version, the requirements
-version of the element, the docs version, and regenerating the authors list
-and bibtex file. All 3 of these steps are triggered by tag creation. This
-means with the bot all that is required for a qiskit project maintainer is to
-push a git tag to github. When coupled with pypi artifact (wheel and sdist)
+on minor releases, the bot will automatically create the branch. These steps are triggered by tag creation. This
+means with the bot all that is required for a Qiskit project maintainer is to
+push a git tag to GitHub. When coupled with pypi artifact (wheel and sdist)
 CI jobs pushing a tag becomes the only required manual step to push a release
 everything else will now be done automatically.
 
 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
+GitHub users can be mentioned in this comment automatically based on the files
 changed in the PR.
 
-In the future the bot may be expanded to automate additional aspects of
-the github workflow for the qiskit community.
+In the future, the bot may be expanded to automate additional aspects of
+the GitHub workflow for the Qiskit community.
 
 ## Configuration
 
 ### Github side configuration
 
-You will need to configure the bot to work with an github user account. This
+You will need to configure the bot to work with an GitHub user account. This
 account will need permission to create releases, push to the repo, etc.
 
 There are two pieces of information needed from that account for the bot to
-work. First you need the github bot user to have an ssh key configured for the
+work. First, you need the GitHub bot user to have an ssh key configured for the
 local user the daemon is run as. This is needed for git based commands like
-pushing branches. Then an access key is needed to be setup for the github api
-access. This is used for API access to github for the repositories.
+pushing branches. Then an access key is needed to be setup for the GitHub api
+access. This is used for API access to GitHub for the repositories.
 
-The last piece of github side configuration needed is to configure the webhook.
+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
@@ -72,13 +68,15 @@ categories:
     "Nothing": null
 notifications:
     ".*":
-        - "@core-team"
+        - @core-team
     qiskit/transpiler:
-        - "@user1"
-        - "@user2"
+        - @user1
+        - @user2
     qiskit/transpiler/passes:
-        - "@user3"
-        - "@user4"
+        # You can escape usernames with ` so that they don't get
+        # GitHub notifications.
+        - `@user3`
+        - `@user4`
 always_notify: true
 notification_prelude: |
     This is a custom prelude
@@ -89,7 +87,7 @@ notification_prelude: |
 
 The details on each option are as follows:
 
-- `categories`: This contains a nested mapping of github labels to changelog
+- `categories`: This contains a nested mapping of GitHub labels to changelog
   sections. If specified at release time when qiskit-bot generates the changelog
   it will look at each merged PR in the release and if any have any matching
   labels that commit summary message will be put under the corresponding
@@ -115,16 +113,17 @@ The details on each option are as follows:
   to notify if an opened PR touches files that match a particular regex (as found
   by Python's stdlib `re.search()` function). For example if you set the path regex
   to `".*"` this would match everything, but using a regex gives you control over
-  exactly how and what matches a particular group. If a path matches the listed
+  exactly how and what matches a particular group. If a path matches, the listed
   usernames will be listed in the notification comment left by the bot on a new PR
-  being opened. This is an additive, so if there is more than 1 match the users
+  being opened. The specified usernames will receive a GitHub mention notification, so you can instead escape the usernames with \` so that instead the reviewer only knows those are relevant people to ping if necessary.
+  The matching is additive, so if there is more than 1 match the users
   from all the matches will be listed in that comment. If this is not specified (and
   `always_notify` is not set) then no comment will be left by the bot when new PRs
   are opened.
-- `always_notify`: If this is specified a notification/comment is always left on PR
+- `always_notify`: If this is specified, a notification/comment is always left on PR
   opening even if there are no matching notification paths. In the case of no
   matching paths just the notification prelude is used.
-- `notification_prelude`: If this is specified the text used for this field will
+- `notification_prelude`: If this is specified, the text used for this field will
   be used as the beginning of every notification comment. If this is not specified
   the following prelude is used:
 

diff --git a/qiskit_bot/notifications.py b/qiskit_bot/notifications.py
@@ -80,8 +80,8 @@ def _process_notification():
                     buf.write(prelude)
                 if notify_list:
                     buf.write(
-                        "\nOne or more of the the following people are "
-                        "requested to review this:\n"
+                        "\nOne or more of the following people are "
+                        "relevant to this code:\n"
                     )
                     for user in sorted(notify_list):
                         buf.write("- %s\n" % user)

diff --git a/tests/test_notifications.py b/tests/test_notifications.py
@@ -59,8 +59,8 @@ def test_basic_notification(self, sub_mock):
         inner_func = sub_mock.call_args_list[0][1]['target']
         inner_func()
         expected_body = notifications.DEFAULT_PRELUDE + (
-            "\nOne or more of the the following people are requested to "
-            "review this:\n- @user1\n- @user2\n"
+            "\nOne or more of the following people are relevant to "
+            "this code:\n- @user1\n- @user2\n"
         )
         gh_mock.get_pull.assert_called_once_with(1234)
         pr_mock.create_issue_comment.assert_called_once_with(expected_body)
@@ -94,8 +94,8 @@ def test_no_prelude_for_team_mbembers(self, sub_mock):
         inner_func = sub_mock.call_args_list[0][1]['target']
         inner_func()
         expected_body = (
-            "\nOne or more of the the following people are requested to "
-            "review this:\n- '@user1'\n- '@user2'\n"
+            "\nOne or more of the following people are relevant to "
+            "this code:\n- '@user1'\n- '@user2'\n"
         )
         gh_mock.get_pull.assert_called_once_with(1234)
         pr_mock.create_issue_comment.assert_called_once_with(expected_body)
@@ -129,8 +129,8 @@ def test_multiple_overlapping_file_notifications(self, sub_mock):
         inner_func = sub_mock.call_args_list[0][1]['target']
         inner_func()
         expected_body = notifications.DEFAULT_PRELUDE + (
-            "\nOne or more of the the following people are requested to "
-            "review this:\n- @user1\n- @user2\n- @user3\n"
+            "\nOne or more of the following people are relevant to "
+            "this code:\n- @user1\n- @user2\n- @user3\n"
         )
 
         gh_mock.get_pull.assert_called_once_with(1234)
@@ -196,8 +196,8 @@ def test_one_hit_multiple_notification_rules(self, sub_mock):
         inner_func = sub_mock.call_args_list[0][1]['target']
         inner_func()
         expected_body = notifications.DEFAULT_PRELUDE + (
-            "\nOne or more of the the following people are requested to "
-            "review this:\n- @user1\n- @user2\n"
+            "\nOne or more of the following people are relevant to "
+            "this code:\n- @user1\n- @user2\n"
         )
         gh_mock.get_pull.assert_called_once_with(1234)
         pr_mock.create_issue_comment.assert_called_once_with(expected_body)
@@ -330,7 +330,7 @@ def test_match_custom_prelude(self, sub_mock):
         inner_func()
         expected_body = """This is my prelude
 
-One or more of the the following people are requested to review this:
+One or more of the following people are relevant to this code:
 - @user1
 - @user2
 """