Merge pull request #92 from ahrefs/yasu/modular-context

Modularize dependencies for GH payload consumption and Slack message sending

Author: yasunariw

documentation/config_docs.md

@@ -1,13 +1,18 @@
-# About
+# Repository Configuration
 
-Config file is where the variables affecting the behaviour of notabot are defined.
+A repository configuration file specifies how notifications should be handled for a given repository. It should be at the root of your monorepo in the main branch. The bot will look for a `notabot.json` file by default, but you can change this behavior with the `--config` flag.
+
+When the bot receives its first incoming GitHub notification, it will query the repository URL to retrieve its configuration file. For subsequent notifications, it will use the cached configuration unless an update is detected.
+
+To update the configuration, simply edit the configuration file and push your changes to GitHub. The bot will detect and apply those changes to the configuration, and will be reflected in the next request onwards.
+
+Refer [here](https://docs.github.com/en/free-pro-team@latest/developers/webhooks-and-events/webhook-events-and-payloads) for more information on GitHub event payload structure.
 
 # Configuration values
 
 **example**
 ```json
 {
-    "offline": "github-api-cache",
     "main_branch_name": "develop",
     "status_rules": {
         ...
@@ -17,16 +22,13 @@ Config file is where the variables affecting the behaviour of notabot are define
     },
     "label_rules": {
         ...
-    },
-    "suppress_cancelled_events": true
+    }
 }
 ```
 
 | value | description | optional | default |
 |-|-|-|-|
 | `main_branch_name` | main branch used for the repo; filtering notifications about merges of main into other branches | Yes | - |
-| `offline` | path to github api data when http calls are not allowed; used for testing | Yes | - |
-| `suppress_cancelled_events` | supresses status cancelled events | Yes | `true` |
 | `status_rules` | status rules config object | No | - |
 | `label_rules` | label rules config object | No | - |
 | `prefix_rules` | prefix rules config object | No | - |
@@ -68,11 +70,11 @@ A json object with fields of bools for each status type.
 | `cancelled` | provide regex to ignore `failure` notifications with a description that matches it | Yes | - |
 
 
-## Label Config
+## Label Options
 
-Label rules apply to PR and issues notifications.
+**Label rules** apply to PR and issue notifications. If a payload matches multiple rules, they are all included.
 
-**example**
+**Example**
 ```json
 "label_rules": {
     "default_channel": "default",
@@ -81,21 +83,18 @@ Label rules apply to PR and issues notifications.
             "allow": [
                 "backend"
             ],
-            "ignore": [],
             "channel": "backend"
         },
         {
             "allow": [
                 "a1"
             ],
-            "ignore": [],
             "channel": "a1-bot"
         },
         {
             "allow": [
                 "a3"
             ],
-            "ignore": [],
             "channel": "a3"
         },
         {
@@ -113,24 +112,24 @@ Label rules apply to PR and issues notifications.
 
 | value | description | optional | default |
 |-|-|-|-|
-| `default_channel` | default channel to notify if no rules match | Yes | no channels will be notified on default |
+| `default_channel` | default channel to notify if no rules match | Yes | don't notify any channel |
 | `rules` | list of `label_rule` objects | No | - |
 
 ### Label Rule
 
+A **label rule** specifies whether or not a Slack channel should be notified, based on the labels present in the given payload. For each rule, `ignore` is a blacklist of labels that should not notify the rule's channel, and `allow` is a whitelist of labels that should. If a label exists in both lists, the `ignore` list takes precedence. If an empty `ignore` list is provided, nothing is ignored. If an empty `allow` list is provided, everything is allowed. Both are optional; if neither are provided, the rule will always generate a notification for its channel.
+
 | value | description | optional | default |
 |-|-|-|-|
-| `allow` | whitelist of label values that match this rule; if list is empty it vacuously satisfies the rule | No | - |
-| `ignore` | blacklist of label values; any labels matching will not match the rule | No | - |
-| `channel` | channel to use as webhook if matching this label rule | No | - |
-
-## Prefix Config
+| `allow` | if notifications match any label in this list, they should be routed to the channel | Yes | all labels allowed if no list provided |
+| `ignore` | if notifications match any label in this list, they shouldn't be routed to the channel (even if they match any allow labels) | Yes | - |
+| `channel` | channel to use as webhook if the rule is matched | No | - |
 
-Prefix rules apply to filenames. If a filename satisfies a prefix rule, the rule's channel will be notified.
+## Prefix Options
 
-The prefix config object is exactly the same as **Label Config** except its `rules` are list of `prefix_rule` objects.
+**Prefix rules** apply to push, commit comment, and status notifications. If a filename satisfies a prefix rule, the rule's channel will be notified. If a filename matches multiple rules, only the one that is matched by the *longest prefix* is included.
 
-**example**
+**Example**
 ```json
 "prefix_rules": {
     "default_channel": "default",
@@ -139,31 +138,28 @@ The prefix config object is exactly the same as **Label Config** except its `rul
             "allow": [
                 "backend/a1"
             ],
-            "ignore": [],
             "channel": "a1"
         },
         {
             "allow": [
                 "backend/a5",
                 "backend/a4"
             ],
-            "ignore": [],
             "channel": "backend"
         },
         {
-            "allow": [],
-            "ignore": [],
             "channel": "all-push-events"
         }
     ]
 },
 ```
 
-
 ### Prefix Rule
 
+A **prefix rule** specifies whether or not a Slack channel should be notified, based on the filenames present in the commits associated with the given payload. The semantics for the `allow` and `ignore` fields are the same as those for label rules (see above).
+
 | value | description | optional | default |
 |-|-|-|-|
-| `allow` | whitelist of strings that if prefixed in the filename matches the rule | No | - |
-| `ignore` | blacklist of strings that if prefixed in the filename does not match the rule | No | - |
-| `channel` | channel to use as webhook if matching this prefix rule | No | - |
+| `allow` | if commit files match any prefix in this list, they should be routed to the channel | Yes | all prefixes allowed if no list provided |
+| `ignore` | if commit files match any prefix in this list, they shouldn't be routed to the channel (even if they match any allow prefixes) | Yes | - |
+| `channel` | channel to use as webhook if the rule is matched | No | - |

documentation/secret_docs.md

@@ -1,10 +1,11 @@
-# About
+# Secrets
 
-Secret file is where sensitive information such as the urls used for webhooks and other tokens are stored.
+A secrets file stores sensitive information. Unlike the repository configuration file, it should not be checked into the monorepo's version control. Instead, store it locally at a location accessible by the bot.
 
-# Secret Values
+# Options
+
+**Example**
 
-**example**
 ```json
 {
     "slack_hooks": [
@@ -42,36 +43,14 @@ Secret file is where sensitive information such as the urls used for webhooks an
 
 | value | description | optional | default |
 |-|-|-|-|
-| `slack_hooks` | list of webhook config objects | No | - |
+| `slack_hooks` | list of channel names (`channel`) and their corresponding webhook endpoint (`url`) | No | - |
 | `gh_token` | specify to grant the bot access to private repositories; omit for public repositories | Yes | - |
 | `gh_hook_token` | specify to ensure the bot only receives GitHub notifications from pre-approved repositories | Yes | - |
 
 ## `gh_token`
 
-### Token generation
-
-Some event notifications (e.g., status, commit comment) require a personal token to be addded to the configuration. To create a personal token, take the following steps:
-1. Verify your email address, if needed.
-1. In the upper-right corner of any page, click your profile photo, then click **Settings**.
-1. In the left sidebar, click **Developer settings**.
-1. In the left sidebar, click **Personal access tokens**.
-1. Click **Generate new token**.
-1. Give your token a descriptive name in the **Note** section.
-1. Grant ***repo*** scope.
-1. Click **Generate token**.
-1. Copy the token to `secrets.json` file in a `gh_token` field.
-
-For more detailed instructions on token generation, refer to https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line.
-
+Some operations, such as fetching a config file from a private repository, or the commit corresponding to a commit comment event, require a personal access token. Refer [here](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token) for detailed instructions on token generation.
 
 ## `gh_hook_token`
-For more information on `gh_hook_token` see [developer.github.com/webhooks/securing](https://developer.github.com/webhooks/securing/)
 
-## Webhook Config
-
-Channels that are defined in rules in config will be mapped to urls defined in the webhook
-
-| value | description | optional | default |
-|-|-|-|-|
-| `url` | url to call to send the message | No | - |
-| `channel` | name of the channel where the message will be posted as used in config | No | - |
+Refer [here](https://docs.github.com/en/free-pro-team@latest/developers/webhooks-and-events/securing-your-webhooks) for more information on securing webhooks with a token.