@mattpolzin/harmony 2.0.0 → 2.2.0

harmony-npm/README.md

@@ -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`, `label`, `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.
@@ -99,7 +110,7 @@ Running `harmony branch` will print the URI for accessing the currently checked
 Many operating systems have an `open` command (though the name "open" is not ubiquitous); this means you can run something like `open $(harmony branch)` to open a web browser to the current branch on GitHub.
 
 ### PR
-Running `harmony pr` 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.
+Running `harmony pr [--draft]` 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 PRs can be created as drafts by specifying the `--draft` flag with the `pr` command.
 
 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 the PR. If you have an `EDITOR` environment variable set, Harmony will use that editor to get the PR description from you. If you have a PR template at `.github/PULL_REQUEST_TEMPLATE.md`, Harmony will also preload that into your editor. If you do not have an `EDITOR` environment variable set, you will still be able to enter a description from the command line but PR templates are only supported when an `EDITOR` is specified.
 
@@ -109,10 +120,20 @@ Many operating systems have an `open` command (though the name "open" is not ubi
 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
@@ -168,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.