Updating maintainer and README documentation

.github/maintainers_guide.md

@@ -13,20 +13,19 @@ All you need to work with this project is a supported version of [Node.js](https
 
 ### Testing
 
-TODO
-
-### Generating Documentation
-
-TODO
+When testing locally, ensure at least linting and unit tests pass by running `npm test`.
+Additionally, sending a PR is highly recommended with every change as there are several GitHub
+Actions jobs that execute what are effectively integration tests for this GitHub Action.
 
 ### Releasing
 
-* Bundle the dependencies by running `npm run build`
 * Update the version in `package.json`
+* Update all references to versions in the README and in the workflow files under `example-workflows/` to refer to the latest release
 * Commit the changes
 * Create a git tag for the new version. Should be in the format `v1.4.0`. `git tag v1.4.0`
 * Push changes up to GitHub `git push origin main --tags`
-
+* Create a GitHub Release based on the tag you just pushed up - this will trigger the publishing
+  GitHub workflow
 
 ## Workflow
 
@@ -42,7 +41,7 @@ As a maintainer, the development you do will be almost entirely off of your fork
 
 ### Branches
 
-`main` is where active development occurs. 
+`main` is where active development occurs.
 
 When developing, branches should be created off of your fork and not directly off of this repository. If working on a long-running feature and in collaboration with others, a corresponding branch of the same name is permitted. This makes collaboration on a single branch possible, as contributors working on the same feature cannot push commits to others' open Pull Requests.
 
@@ -74,4 +73,4 @@ relevant once again, reopening is great and better than creating a duplicate iss
 
 ## Everything else
 
-When in doubt, find the other maintainers and ask.
+When in doubt, find the other maintainers and ask.

README.md

@@ -4,25 +4,30 @@ Send data into Slack using this GitHub Action! This package has three different
 
 1) Send data to Slack's Workflow Builder (requires a paid Slack instance).
 2) Send data via a Slack app to post to a specific channel (use an existing custom app or create a new one).
-3) Send data via an Slack's Incoming Webhook URL (use an existing custom app or create a new one)
+3) Send data via a Slack Incoming Webhook URL (use an existing custom app or create a new one).
 
 The recommended way to use this action is with Slack's Workflow Builder (if you're on a paid Slack plan).
 
-## Slack Workflow Builder Route
+## Technique 1: Slack Workflow Builder
 
-Sending data to [Slack's Workflow builder](https://slack.com/intl/en-ca/features/workflow-automation) is the recommended way to use this action. This action will send data into Slack via a webhook URL. Follow [these steps to create a Slack workflow using webhooks](https://slack.com/intl/en-ca/help/articles/360041352714-Create-more-advanced-workflows-using-webhooks). The Slack workflow webhook url will be in the form of `https://hooks.slack.com/workflows/....`. The payload sent by this GitHub action will be flattened (all nested keys moved top level) and stringified since Slack's workflow builder only supports top level string values in payloads.
+> ❗️ This approach requires a paid Slack plan
 
-You need to define expected variables in the payload the webhook will receive. If these variables are missing in the payload, an error is returned.
+Sending data to [Slack's Workflow builder](https://slack.com/features/workflow-automation) is the recommended way to use this action. This action will send data into Slack via a webhook URL. Follow [these steps to create a Slack workflow using webhooks][create-webhook]. The Slack workflow webhook URL will be in the form `https://hooks.slack.com/workflows/....`. The payload sent by this GitHub action will be flattened (all nested keys moved to the top level) and stringified since Slack's workflow builder only supports top level string values in payloads.
+
+As part of the [workflow setup](https://slack.com/help/articles/360041352714-Create-more-advanced-workflows-using-webhooks#workflow-setup),
+you will need to define expected variables in the payload the webhook will receive (described in the "Create custom variables" section of the docs). If these variables are missing in the payload, an error is returned.
 
 ### Setup
 
-* [Create a Slack workflow webhook](https://slack.com/intl/en-ca/help/articles/360041352714-Create-more-advanced-workflows-using-webhooks)
-* Copy the webhook URL (`https://hooks.slack.com/workflows/....`) and [add it as a secret in your repo settings](https://docs.github.com/en/free-pro-team@latest/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository) named `SLACK_WEBHOOK_URL`.
-* Add a step to your GitHub action to send data to your Webhook
+* [Create a Slack workflow webhook][create-webhook].
+* Copy the webhook URL (`https://hooks.slack.com/workflows/....`) and [add it as a secret in your repo settings][repo-secret] named `SLACK_WEBHOOK_URL`.
+* Add a step to your GitHub action to send data to your Webhook.
 * Configure your Slack workflow to use variables from the incoming payload from the GitHub Action. You can select where you want to post the data and how you want to format it in Slack's worflow builder interface.
 
 ### Usage
 
+Add this Action as a [step][job-step] to your project's GitHub Action Workflow file:
+
 ```
 - name: Send GitHub Action trigger data to Slack workflow
   id: slack
@@ -43,19 +48,22 @@ or
     SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
 ```
 
-## Slack App Route
+## Technique 2: Slack App
 
-This route allows your GitHub Actions job to post a message in a Slack channel or direct message by utilizing [chat.postMessage](https://api.slack.com/methods/chat.postMessage) API method. With this route, you can instantly post a message without setting up workflows.
+By creating a new Slack app or using an existing one, this approach allows your GitHub Actions job to post a message in a Slack channel or direct message by utilizing the [chat.postMessage](https://api.slack.com/methods/chat.postMessage) API method. Using this approach you can instantly post a message without setting up Slack workflows.
 
 ## Setup
 
-* [Create a Slack App](https://api.slack.com/apps) for your workspace (alternatively use an existing app you have already created and installed)
-* Add the [`chat.write`](https://api.slack.com/scopes/chat:write) bot scope under **OAuth & Permissions**
-* Install the app to your workspace
-* Invite the bot user into the channel (`/invite @bot_user_name`)
+* [Create a Slack App][apps] for your workspace (alternatively use an existing app you have already created and installed).
+* Add the [`chat.write`](https://api.slack.com/scopes/chat:write) bot scope under **OAuth & Permissions**.
+* Install the app to your workspace.
+* Copy the app's Bot Token from the **OAuth & Permissions** page and [add it as a secret in your repo settings][repo-secret] named `SLACK_BOT_TOKEN`.
+* Invite the bot user into the channel you wish to post messages to (`/invite @bot_user_name`).
 
 ### Usage
 
+Add this Action as a [step][job-step] to your project's GitHub Action Workflow file:
+
 ```
 - name: Post to a Slack channel
   id: slack
@@ -67,17 +75,19 @@ This route allows your GitHub Actions job to post a message in a Slack channel o
     SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
 ```
 
-## Slack Incoming Webhook Route
+## Technique 3: Slack Incoming Webhook
 
-This route allows your GitHub Actions job to post a message in a Slack channel or direct message by utilizing [Incoming Webhooks](https://api.slack.com/messaging/webhooks). With this route, you can instantly post a message.
+This approach allows your GitHub Actions job to post a message to a Slack channel or direct message by utilizing [Incoming Webhooks](https://api.slack.com/messaging/webhooks).
 
-Incoming Webhooks conform to the same rules and functionality as any of our other messaging APIs. You can make your posted messages as simple as a single line of text, or make them really useful with [interactive components](https://api.slack.com/messaging/interactivity). To make the message more expressive and useful use [Block Kit](https://api.slack.com/block-kit) to build and test visual components.
+Incoming Webhooks conform to the same rules and functionality as any of Slack's other messaging APIs. You can make your posted messages as simple as a single line of text, or make them really useful with [interactive components](https://api.slack.com/messaging/interactivity). To make the message more expressive and useful use [Block Kit](https://api.slack.com/block-kit) to build and test visual components.
 
 ## Setup
 
-* [Create a Slack App](https://api.slack.com/apps) for your workspace (alternatively use an existing app you have already created and installed)
-* Add the [incoming-webhook](https://api.slack.com/scopes/incoming-webhook) bot scope under **OAuth & Permissions**
-* Install the app to your workspace (you will select a channel to notify)
+* [Create a Slack App][apps] for your workspace (alternatively use an existing app you have already created and installed).
+* Add the [`incoming-webhook`](https://api.slack.com/scopes/incoming-webhook) bot scope under **OAuth & Permissions**.
+* Install the app to your workspace (you will select a channel to notify).
+* Activate and create a new webhook under **Incoming Webhooks**.
+* Copy the Webhook URL from the Webhook you just generated [add it as a secret in your repo settings][repo-secret] named `SLACK_WEBHOOK_URL`.
 
 ### Usage
 
@@ -99,3 +109,8 @@ See [CONTRIBUTING](.github/contributing.md).
 ## License
 
 See [LICENSE](LICENSE).
+
+[create-webhook]: https://slack.com/intl/en-ca/help/articles/360041352714-Create-more-advanced-workflows-using-webhooks
+[job-step]: https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idsteps
+[repo-secret]: https://docs.github.com/en/free-pro-team@latest/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository
+[apps]: https://api.slack.com/apps

package.json

@@ -1,6 +1,6 @@
 {
   "name": "slack-github-action",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "The official slack github action. Use this to send data into your Slack workspace",
   "main": "dist/index.js",
   "scripts": {