@mattpolzin/harmony 1.3.0 → 2.1.0

harmony-npm/README.md

@@ -4,7 +4,7 @@ Harmony is a small tool that helps teams keep GitHub reviews running smoothly. I
 
 ## Dependencies
 ### Runtime
-Running Harmony only requires NodeJS 12+ (and a local installation of `git`).
+Running Harmony only requires NodeJS 14+ (and a local installation of `git`).
 ### Build time
 Building the latest commits of Harmony requires a HEAD build of the Idris 2 compiler. Each release page also indicates the version of Idris 2 that particular release will build against.
 
@@ -30,7 +30,7 @@ You can install Harmony via npm directly by running `npm install -g @mattpolzin/
 You can install any Harmony release by downloading the `harmony-npm.tar.gz` file from the GitHub Release page, unzipping it, and running `npm install --global`.
 
 ### From Source
-The normal installation assumes a HEAD build of Idris 2 is installed. For an alternative, see the [Docker Build](#docker-build) instructions below.
+The build script assumes a HEAD build of Idris 2 is installed on your system. For an alternative, see the [Docker Build](#docker-build) instructions below.
 
 Build Harmony from source with a call to `make`. Then install it globally with `make install`.
 
@@ -91,7 +91,18 @@ Would you like harmony to assign teams in addition to individuals when it assign
 Creating config...
 ```
 
-Once configured, Harmony supports the following commands: `branch`, `pr`, `assign`, `contribute`, `whoami`, `reflect`, `list`, `graph`, `config`, and `sync`.
+Once configured, Harmony supports the following commands: `config`, `branch`, `pr`, `label`, `assign`, `contribute`, `whoami`, `reflect`, `list`, `graph`, and `sync`.
+
+### Config
+Running `harmony config <property>` will read the given configuration property. `harmony config <property> <value>` will set the configuration property.
+
+Not all configuration properties can be read/set with this command.
+#### Properties
+- `assignTeams` (`true`/`false`) -- When picking a reviewer from a team, assign the team as a reviewer as well.
+- `assignUsers` (`true`/`false`) -- When assigning a team as a reviewer, pick a user to review as well.
+- `commentOnAssign` (`true`/`false`) -- When assigning a reviewer chosen by Harmony, comment on the pull request.
+- `defaultRemote` (optional string) -- When pushing new branches, what remote destination should be used.
+- `githubPAT` (optional string) -- If the `$GITHUB_PAT` environment variable is not set, this Personal Access Token is used to authenticate with GitHub.
 
 ### Branch
 Running `harmony branch` will print the URI for accessing the currently checked out branch on GitHub.
@@ -105,11 +116,24 @@ If you need to create a PR still, you will be prompted for a branch to open the
 
 Many operating systems have an `open` command (though the name "open" is not ubiquitous); this means you can run something like `open $(harmony pr)` to open a web browser to an existing PR for the current branch.
 
+### Label
+Running `harmony label {<label>} [...]` will help you create a PR if one does not exist yet and then it will apply the given labels to the PR.
+
 ### Assign
-Running `harmony assign {<team> | +<user>} [...]` will help you create a PR if one does not exist yet and then it will pick someone to review the PR (from one of the listed teams) and assign both that user and the teams you listed as reviewers of the PR.
+Running `harmony assign {<team> | +<user>} [#<label>] [...]` will help you create a PR if one does not exist yet and then it will assign teams and/or users to the PR.
+
+If `harmony config assignUsers` is `True` (defualt) then harmony will pick someone to review the PR (from one of the listed teams) and assign them to the PR. If `harmony config assignTeams` is `True` then harmony will assign the teams you listed as reviewers of the PR. If `harmony config commentOnAssign` is `True` then harmony will comment on the Pull Request indicating that teams & users were "harmoniously assigned" -- this comment will @mention assigned users so it may be useful or annoying depending on the assigned user's GitHub notification settings.
 
 You can also require that specific additional users (on top of the one Harmony will pick for you) are assigned to the PR. You do this by specifying those users' logins prefixed with '+' as arguments to Harmony.
 
+If your team has GitHub set up to auto-assign individuals when a team is requested for review, you probably want to tell harmony not to also pick someone using its heuristics. You can run the following `config` commands to tell harmony to assign a team but not also pick an individual from that team:
+```shell
+harmony config assignTeams true
+harmony config assignUsers false
+```
+
+You can optionally apply any number of labels to the PR at the same time as assigning reviewers by prefixing the labels with '#'.
+
 #### Examples
 Assign the most available reviewer from the "developers" GitHub Team:
 ```shell
@@ -165,17 +189,6 @@ Running `harmony graph <team>` will graph the relative review workload of each o
 
 You can optionally graph completed PR reviews with the `--completed` flag as well, though these are not considered for Harmony's weighting algorithm for review workload.
 
-### Config
-Running `harmony config <property>` will read the given configuration property. `harmony config <property> <value>` will set the configuration property.
-
-Not all configuration properties can be read/set with this command.
-#### Properties
-- `assignTeams` -- When picking a reviewer from a team, assign the team as a reviewer as well.
-- `assignUsers` -- When assigning a team as a reviewer, pick a user to review as well.
-- `commentOnAssign` -- When assigning a reviewer chosen by Harmony, comment on the pull request.
-- `defaultRemote` -- When pushing new branches, what remote destination should be used.
-- `githubPAT` -- If the `$GITHUB_PAT` environment variable is not set, this Personal Access Token is used to authenticate with GitHub.
-
 ### Sync
 Running `harmony sync` will sync the locally configured team slugs and user logins that are used by auto-completion for Harmony. This sync is also performed automatically the first time you run Harmony after more than a day without the configuration being synced.