@mattpolzin/harmony 6.0.0 → 6.1.0

package/README.md

@@ -1,4 +1,9 @@
-% harmony(1) Version 6.0.0 | Harmony User's Guide
+<!--
+ This file is auto-generated.
+
+ Edit the files in the `docs/` directory and run `make README.md` and `make
+ manpage` to regenerate those respective files.
+-->
 
 # NAME
 Harmony - Harmonize with coworkers around GitHub reviewing
@@ -56,24 +61,8 @@ to run all the tests:
   - `xargs`
 
 ## Installation
-For any installation, you need to have a GitHub 
-[Personal Access Token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token).
-
-Your Personal Access Token should have the following permissions:
-- `repo` (Full control of private repositories)
-- `read:org` (Read org and team membership, read org projects)
-- `read:user`
-- `user:email`
-- `read:discussion`
-- `read:enterprise` (Read enterprise profile data)
-
-You can either add the PAT to your environment as the `GITHUB_PAT` (or
-alternatively `GH_TOKEN`) variable (perhaps exporting it from your shell
-resource file or profile) or you can store your PAT in Harmony's config file.
-The first time you start Harmony, it will ask you to configure your PAT if you
-don't want to use the Environment variable. You only need one of (a) the ENV var
-and (b) the config property and the environment variable will take precedence if
-you have both set.
+You can install Harmony in several different ways, though by far the easiest is
+to install it via the Node Package Manager (NPM).
 
 ### NPM
 You can install Harmony via npm directly by running 
@@ -131,21 +120,40 @@ globally:
 npm install --global
 ```
 
-### Bash completion
+## Bash completion
 Set up Bash completion by adding the following to your Bash resource file or
 profile:
 ```shell
 eval "$(harmony --bash-completion-script)"
 ```
 
-### Zsh completion
+## Zsh completion
 Zsh completion is supported via `bashcompinit` and can be loaded by adding the
 following to your Zsh resource file or profile:
 ```shell
 eval "$(harmony --zsh-completion-script)"
 ```
 
-## Usage
+## Initial configuration
+For most things harmony does, you need to have a GitHub 
+[Personal Access Token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token).
+
+Your Personal Access Token should have the following permissions:
+- `repo` (Full control of private repositories)
+- `read:org` (Read org and team membership, read org projects)
+- `read:user`
+- `user:email`
+- `read:discussion`
+- `read:enterprise` (Read enterprise profile data)
+
+You can either add the PAT to your environment as the `GITHUB_PAT` (or
+alternatively `GH_TOKEN`) variable (perhaps exporting it from your shell
+resource file or profile) or you can store your PAT in Harmony's config file.
+The first time you start Harmony, it will ask you to configure your PAT if you
+don't want to use the Environment variable. You only need one of (a) the ENV var
+and (b) the config property and the environment variable will take precedence if
+you have both set.
+
 The first time you start Harmony in any particular folder, you will be asked to
 provide some information about the GitHub repository you are working with. This
 information is stored in a file named `harmony.json` in the current working
@@ -177,9 +185,10 @@ Would you like harmony to request team reviews in addition to individuals when i
 Creating config...
 ```
 
-Once configured, Harmony supports the following commands: `config`, `branch`,
-`pr`, `quick`, `label`, `request` (also aliased to `rq`), `contribute`,
-`whoami`, `reflect`, `list`, `graph`, `health`, and `sync`.
+## Usage
+Once configured, Harmony supports the following commands that are documented
+below: `config`, `branch`, `pr`, `quick`, `label`, `request` (also aliased to
+`rq`), `contribute`, `whoami`, `reflect`, `list`, `graph`, `health`, and `sync`.
 
 **Note on color output:**
 Harmony uses colored output for some commands. You can adjust these colors
@@ -300,6 +309,7 @@ Graph all open PRs grouped by the month when each was created.
 The idea is that a healthy repository does not have many old PRs still open
 because those PRs represent effort spent by developers that hasn't yet paid off.
 
+<!-- image location is intentionally relative to repository root -->
 ![Health Screenshot](./docs/images/health.png)
 
 ## `help [subcommand]`
@@ -390,6 +400,7 @@ description.
 ## `reflect`
 Show a summary of your review requests and authored pull requests.
 
+<!-- image location is intentionally relative to repository root -->
 ![Reflect Screenshot](./docs/images/reflect.png)
 
 ## `request {team-slug | +user-login} [options]`