@mattpolzin/harmony 5.8.0 → 6.1.0

package/README.md

@@ -1,4 +1,9 @@
-% harmony(1) Version 5.8.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
@@ -48,25 +53,16 @@ particular release will build against.
 Alternatively, you can build Harmony with Docker (see 
 [Docker Build](#docker-build)).
 
-## 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)
+### Testing
+Tests can be run with `make test`. You'll need a few common tools in your `PATH`
+to run all the tests:
+  - `realpath`
+  - `sed`
+  - `xargs`
 
-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.
+## Installation
+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 
@@ -124,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
@@ -170,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
@@ -293,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]`
@@ -312,12 +329,13 @@ organization.
 
 Running `harmony list <team>` will list the members of the given GitHub Team.
 
-## `pr [--draft] [-i/--into {<branch-name>}] [#label, ...]`
+## `pr [--draft | --ready] [-i/--into {<branch-name>}] [#label, ...]`
 With a branch checked out will reach out to GitHub to determine if there is an
 open PR for that branch. If there is a PR, Harmony will print a URI that can be
 used to view the PR. If there is not a PR, Harmony will help you create one. New
 and existing PRs can be marked as drafts by specifying the `--draft` flag with
-the `pr` command.
+the `pr` command or they can be marked as ready for review with the `--ready`
+flag. The default behavior for new PRs is to mark them ready.
 
 If you need to create a PR still, you will be prompted for a branch to open the
 PR against (merge into, eventually), a title for the PR, and a description for
@@ -382,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]`