Improve README

README.md

@@ -1,91 +1,92 @@
 # action-npm-publish
 
-This is a GitHub action that handles publishing to NPM for a project that represents a single package (in the case of a polyrepo) or a collection of packages (in the case of a monorepo).
+This is a GitHub action that publishes one or more packages within a repo to NPM.
 
-- For a polyrepo project, the action will publish the package using its current version as per `package.json`.
+- For a single-package repo, the action will publish the package at the version listed in `package.json`.
+- For a multi-package repo (monorepo), the action will iterate through the packages specified by the `workspaces` field in `package.json` and publish each one at the version listed in its `package.json`.
 
-- For a monorepo, the action will publish each workspace package (the set of packages matched via the `workspaces` field in `package.json`, recursively) using its current version as per `package.json`. (Any package which has already been published at its current version will be skipped.)
+Designed for use with [`action-publish-release`](https://github.com/MetaMask/action-publish-release).
 
+## Usage
 
-## Requirements
+### Prequisites
 
-**This action assumes that Yarn is installed and that the package is using Yarn v3.** It may fail for other Yarn versions or other package managers.
+- Ensure your project is using Yarn. Other package managers may not work as expected.
+- You'll need to create an NPM token for your repo and set it as a secret under an `npm-publish` environment so that releases can go through an approval step. Reach out to the `@metamask/npm-publishers` group for help on creating the NPM token and setting up this environment.
+- If your project is using Yarn Modern, Yarn is configured to use the `node-modules` linker, and your project defines a `prepack` script for any releasable packages, ensure that the file `node_modules/.yarn-state.yml` is present before this action is invoked. This file is generated automatically when installing dependencies. If you want to publish without dependencies present, you can instantiate an empty state file or restore one from a cache.
+- The `slack-webhook-url` option for this action makes use of another action, `slackapi/slack-github-action@007b2c3c751a190b6f0f040e47ed024deaa72844`. This action is authored by a Marketplace "verified creator". If your repository or organization restricts which actions can be used and does not allow Marketplace verified creators by default, ensure that this is listed as an allowed action.
 
-If your project is configured to use the `node-modules` linker and defines a `prepack` script for any releasable packages, you will need to ensure that the file `node_modules/.yarn-state.yml` is present before this action is invoked. This file is generated automatically when installing dependencies. If you want to publish without dependencies present, you can instantiate an empty state file or restore one from a cache.
+### Quick start
 
-This action depends upon the action `slackapi/slack-github-action@007b2c3c751a190b6f0f040e47ed024deaa72844`. This action is authored by a Marketplace "verified creator". If your repository or organization restricts which actions can be used and does not allow Marketplace verified creators by default, ensure that this action is listed as an allowed action.
+The [`publish-release` workflow](https://github.com/MetaMask/metamask-module-template/blob/main/.github/workflows/publish-release.yml) from the [module template](https://github.com/MetaMask/metamask-module-template) is a live example of how we use this action in many MetaMask projects. In particular it demonstrates:
 
-## Usage
+- How we typically check out and set up the repo beforehand
+- How we place the publishing step under an approval step
+- How we notify approvers in Slack
 
-### Quick start
+The sections below go into more detail on use cases.
 
-If you're in a hurry, take a look at the [`publish-release` workflow](https://github.com/MetaMask/metamask-module-template/blob/main/.github/workflows/publish-release.yml) from the [module template](https://github.com/MetaMask/metamask-module-template), which uses this action to publish appropriate packages whenever a release commit is merged, once in dry-run mode and once in "real" mode. (A release commit is a commit that changes the version of the primary package within the project, whether that is the sole package in the case of a polyrepo package, or the root package in the case of a monorepo.) Note that in order to use this workflow file in your project, you will need to create an `npm-publish` environment via your repository's settings and set the `NPM_TOKEN` secret within this environment to the authentication token for the MetaMask organization on `npmjs.com`.
+### Preparing packages in dry-run mode
 
-### Publish mode
+By default, without supplying `npm-token`, packages will be prepared for publishing, but no publishing will actually occur. This is useful so that approvers can inspect the package before it is published.
 
-Add the following to a job's list of steps. This requires that you set the `NPM_TOKEN` secret in your repository's settings to an appropriate NPM authentication token:
+Add this to a job's steps in your workflow:
 
 ```yaml
-- uses: MetaMask/action-npm-publish@v2
-  with:
-    npm-token: ${{ secrets.NPM_TOKEN }}
+- uses: MetaMask/action-npm-publish@v5
 ```
 
-### Dry run mode
+### Publishing to NPM
 
-If you omit `npm-token`, then packages will be prepared for publishing, but no publishing will actually occur:
+If you supply `npm-token`, then publishing will actually occur. You will probably want to pair this with the previous step:
 
 ```yaml
-- uses: MetaMask/action-npm-publish@v4
+- uses: MetaMask/action-npm-publish@v5
+  with:
+    npm-token: ${{ secrets.NPM_TOKEN }}
 ```
 
-### Slack announce
+### Automatically requesting approvals in Slack
 
-You can optionally send deployment announcements to Slack by providing a `slack-webhook-url` input:
+This assumes that you've created an `npm-publish` environment and placed it behind an approval step.
 
-The absolute minimum configuration for this is:
+You can automatically notify `@MetaMask/npm-publishers` that a release is ready to be approved by providing a `slack-webhook-url` input:
 
 ```yaml
-- uses: MetaMask/action-npm-publish@v4
+- uses: MetaMask/action-npm-publish@v5
   with:
     slack-webhook-url: ${{ secrets.SLACK_WEBHOOK_URL }}
+    subteam: S042S7RE4AE  # @metamask-npm-publishers
 ```
 
-We've added the ability to customize the message posted in Slack and those optional inputs are as follows:
+This posts a message to `#metamask-dev`, such as:
+
+![example deployment](docs/example-deployment.png)
 
-- `icon-url`
-- `username`
-- `subteam`
-- `channel`
+Here is another example that customizes the icon URL, bot name, and channel:
 
-example:
+For example:
 
 ```yaml
-- uses: MetaMask/action-npm-publish@v4
+- uses: MetaMask/action-npm-publish@v5
   with:
     slack-webhook-url: ${{ secrets.SLACK_WEBHOOK_URL }}
     icon-url: https://ricky.codes/me.jpg
     username: rickybot
     # re subteam, see: https://api.slack.com/reference/surfaces/formatting#mentioning-groups
-    subteam: S042S7RE4AE # @metamask-npm-publishers
+    subteam: S042S7RE4AE  # @metamask-npm-publishers
     channel: dev-channel
 ```
 
-You can read more about these option in the [API](#API) section below
-
-![image](https://user-images.githubusercontent.com/675259/203841602-124d537d-7476-4263-a17c-6d05b68c37d0.png)
+You can read more about these options in the [API](#api) section below.
 
 ## API
 
 ### Inputs
 
 - **`npm-token`** _(optional)_. The auth token associated with the registry that Yarn commands will use to access and publish packages. If omitted, the action will perform a dry-run publish.
-
 - **`slack-webhook-url`** _(optional)_. The incoming webhook URL associated with your Slack application for announcing releases to a Slack channel. This can be added under the "Incoming Webhooks" section of your Slack app configuration.
-
-#### The following inputs only apply if `slack-webhook-url` is set...
-
-- **`icon-url`** _(optional)_. Url to the avatar used for the bot in Slack. If not set this defaults to the avatar in this repository.
-- **`username`** _(optional)_. The name of the bot as it appears on Slack. If not set this defaults to `MetaMask bot`.
-- **`subteam`** _(optional)_. Use this if you want to ping a subteam of individuals on Slack using `@`.
-- **`channel`** _(optional)_. Use this if you want to post to a channel other than the default: `metamask-dev`.
+- **`icon-url`** _(optional)_. Only applicable if `slack-webhook-url` is set. URL to the avatar used for the bot in Slack. Defaults to the avatar in this repository.
+- **`username`** _(optional)_. Only applicable if `slack-webhook-url` is set. The name of the bot as it appears on Slack. Defaults to `MetaMask bot`.
+- **`subteam`** _(optional)_. Only applicable if `slack-webhook-url` is set. Use this if you want to ping a subteam of individuals on Slack using `@`.
+- **`channel`** _(optional)_. Only applicable if `slack-webhook-url` is set. Use this if you want to post to a channel other than the default: `metamask-dev`. (Do not include the leading `#`.)