@mattpolzin/harmony 5.4.2 → 5.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +145 -89
- package/harmony +1823 -1794
- package/man/harmony.1 +511 -0
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -1,5 +1,27 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
% harmony(1) Version 5.5.1 | Harmony User's Guide
|
|
2
|
+
|
|
3
|
+
# NAME
|
|
4
|
+
Harmony - Harmonize with coworkers around GitHub reviewing
|
|
5
|
+
|
|
6
|
+
# SYNOPSIS
|
|
7
|
+
`harmony branch` \
|
|
8
|
+
`harmony config {property} [value]` \
|
|
9
|
+
`harmony contribute [options] {uri | pr-number}` \
|
|
10
|
+
`harmony graph [options] {team-slug}` \
|
|
11
|
+
`harmony health` \
|
|
12
|
+
`harmony help [subcommand]` \
|
|
13
|
+
`harmony label {label} [...]` \
|
|
14
|
+
`harmony list [team-slug]` \
|
|
15
|
+
`harmony pr [options]` \
|
|
16
|
+
`harmony quick` \
|
|
17
|
+
`harmony reflect` \
|
|
18
|
+
`harmony request {team-slug | +user-login} [options]` \
|
|
19
|
+
`harmony rq {team-slug | +user-login} [options]` \
|
|
20
|
+
`harmony sync` \
|
|
21
|
+
`harmony version` \
|
|
22
|
+
`harmony whoami`
|
|
23
|
+
|
|
24
|
+
# DESCRIPTION
|
|
3
25
|
Harmony is a small tool that helps teams keep GitHub reviews running smoothly. It takes the work out of picking someone from a pool of developers to review a new PR. Harmony does this by heuristically determining who on a particular GitHub Team has the least current/recent review workload.
|
|
4
26
|
|
|
5
27
|
Harmony offers a heuristic for PR review requests that is different than GitHub's round robin or weighted algorithms, but Harmony can also work well even if your team uses GitHub's automatic PR review requests ([see below](#deferring-to-github)).
|
|
@@ -56,7 +78,7 @@ The build script assumes a HEAD build of Idris 2 is installed on your system. Fo
|
|
|
56
78
|
|
|
57
79
|
Build Harmony from source with a call to `make`. Then install it globally with `make install`.
|
|
58
80
|
|
|
59
|
-
|
|
81
|
+
### Docker Build
|
|
60
82
|
If you want to build Harmony without installing Idris 2 on your system, you can build Harmony within a Docker container and then install the resulting Javascript onto your system.
|
|
61
83
|
|
|
62
84
|
First, download the latest nightly Docker image:
|
|
@@ -66,7 +88,9 @@ docker pull mattpolzin2/idris-docker:nightly
|
|
|
66
88
|
|
|
67
89
|
Then, from a directory containing this Harmony git repository, build Harmony:
|
|
68
90
|
```shell
|
|
69
|
-
docker run --rm -v "$(pwd):/build"
|
|
91
|
+
docker run --rm -v "$(pwd):/build" \
|
|
92
|
+
mattpolzin2/idris-docker:nightly \
|
|
93
|
+
bash -c "apt-get update && apt-get install -y git && cd /build && make"
|
|
70
94
|
```
|
|
71
95
|
|
|
72
96
|
At this point you are done with Docker. From the same directory, install Harmony globally:
|
|
@@ -112,94 +136,51 @@ Would you like harmony to request team reviews in addition to individuals when i
|
|
|
112
136
|
Creating config...
|
|
113
137
|
```
|
|
114
138
|
|
|
115
|
-
Once configured, Harmony supports the following commands: `config`, `branch`, `pr`, `label`, `request` (also aliased to `rq`), `contribute`, `whoami`, `reflect`, `list`, `graph`, `health`, and `sync`.
|
|
139
|
+
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`.
|
|
116
140
|
|
|
117
141
|
**Note on color output:**
|
|
118
142
|
Harmony uses colored output for some commands. You can adjust these colors slightly with the `theme` configuration option. You can also use the `NO_COLOR` environment variable to disable all colored output. Lastly, Harmony will avoid colored output when it determines `stdout` is not a TTY device (as is the case for e.g. redirecting harmony output into a file or piping into `cat`: `harmony ... | cat`).
|
|
119
143
|
|
|
120
|
-
|
|
121
|
-
Running `harmony config <property>` will read the given configuration property. `harmony config <property> <value>` will set the configuration property.
|
|
144
|
+
# SUBCOMMANDS
|
|
122
145
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
- `requestTeams` (`true`/`false`) -- When picking a reviewer from a team, request the team as a reviewer as well.
|
|
126
|
-
- `requestUsers` (`true`/`false`) -- When requesting a team as a reviewer, pick a user to review as well.
|
|
127
|
-
- `commentOnRequest` (`none`/`name`/`at-mention`) -- When requesting a reviewer chosen by Harmony, comment on the pull request or not.
|
|
128
|
-
- `branchParsing` (`none`/`jira`/`github`) -- Optionally extract a Jira ticket slug or GitHub issue number from the branch name and prepend it to the PR title or body to link the PR and ticket/issue.
|
|
129
|
-
- `defaultRemote` (optional string) -- When pushing new branches, what remote destination should be used.
|
|
130
|
-
- `mainBranch` (optional string) -- When creating a PR, this is the default base branch.
|
|
131
|
-
- `theme` (`dark`/`light`) -- Use colors suited better for either a dark or light Terminal background.
|
|
132
|
-
- `githubPAT` (optional string) -- If the `$GITHUB_PAT` and `$GH_TOKEN` environment variables are not set, this Personal Access Token is used to authenticate with GitHub.
|
|
133
|
-
|
|
134
|
-
### Branch
|
|
135
|
-
Running `harmony branch` will print the URI for accessing the currently checked out branch on GitHub.
|
|
146
|
+
## `branch`
|
|
147
|
+
Print the URI for accessing the currently checked out branch on GitHub.
|
|
136
148
|
|
|
137
149
|
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.
|
|
138
150
|
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
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.
|
|
151
|
+
## `config {property} [value]`
|
|
152
|
+
Read the given configuration property. `harmony config <property> <value>` will set the configuration property.
|
|
143
153
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
If you are using harmony from a script or some other environment without TTY support, harmony will print a GitHub URL that can be used to create the PR. This mode of operation will ignore the `--draft` and `#label` options.
|
|
154
|
+
Not all configuration properties can be read/set with this command.
|
|
147
155
|
|
|
148
|
-
|
|
156
|
+
### Properties
|
|
149
157
|
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
```shell
|
|
153
|
-
harmony pr --draft
|
|
154
|
-
```
|
|
158
|
+
`requestTeams` (`true`/`false`)
|
|
159
|
+
: When picking a reviewer from a team, request the team as a reviewer as well.
|
|
155
160
|
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
harmony pr #urgent
|
|
159
|
-
```
|
|
161
|
+
`requestUsers` (`true`/`false`)
|
|
162
|
+
: When requesting a team as a reviewer, pick a user to review as well.
|
|
160
163
|
|
|
161
|
-
|
|
162
|
-
|
|
164
|
+
`commentOnRequest` (`none`/`name`/`at-mention`)
|
|
165
|
+
: When requesting a reviewer chosen by Harmony, comment on the pull request or not.
|
|
163
166
|
|
|
164
|
-
|
|
167
|
+
`branchParsing` (`none`/`jira`/`github`)
|
|
168
|
+
: Optionally extract a Jira ticket slug or GitHub issue number from the branch name and prepend it to the PR title or body to link the PR and ticket/issue.
|
|
165
169
|
|
|
166
|
-
|
|
167
|
-
|
|
170
|
+
`defaultRemote` (optional string)
|
|
171
|
+
: When pushing new branches, what remote destination should be used.
|
|
168
172
|
|
|
169
|
-
|
|
173
|
+
`mainBranch` (optional string)
|
|
174
|
+
: When creating a PR, this is the default base branch.
|
|
170
175
|
|
|
171
|
-
|
|
176
|
+
`theme` (`dark`/`light`)
|
|
177
|
+
: Use colors suited better for either a dark or light Terminal background.
|
|
172
178
|
|
|
173
|
-
|
|
179
|
+
`githubPAT` (optional string)
|
|
180
|
+
: If the `$GITHUB_PAT` and `$GH_TOKEN` environment variables are not set, this Personal Access Token is used to authenticate with GitHub.
|
|
174
181
|
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
#### Deferring to GitHub
|
|
178
|
-
If your team has GitHub set up to auto-request reviews from 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 request a team but not also pick an individual from that team:
|
|
179
|
-
```shell
|
|
180
|
-
harmony config requestTeams true
|
|
181
|
-
harmony config requestUsers false
|
|
182
|
-
```
|
|
183
|
-
This does not prevent you from requesting specific individuals with the `+<user>` syntax described above.
|
|
184
|
-
|
|
185
|
-
#### Examples
|
|
186
|
-
Request review from the most available reviewer from the "developers" GitHub Team:
|
|
187
|
-
```shell
|
|
188
|
-
harmony request developers
|
|
189
|
-
```
|
|
190
|
-
|
|
191
|
-
Request review from the most available reviewer from either the "frontend" or "backend" GitHub Team:
|
|
192
|
-
```shell
|
|
193
|
-
harmony request frontend backend
|
|
194
|
-
```
|
|
195
|
-
|
|
196
|
-
Request review from the most available reviewer from the "web" team and additionally request review from the users with logins "carl001" and "emmaham":
|
|
197
|
-
```shell
|
|
198
|
-
harmony request web +carl001 +emmaham
|
|
199
|
-
```
|
|
200
|
-
|
|
201
|
-
### Contribute
|
|
202
|
-
Running `harmony contribute` will print the URI of the oldest non-draft PR waiting for your review. If you are not requested for review on any PRs, Harmony will suggest a PR that your review is not requested on.
|
|
182
|
+
## `contribute [options]`
|
|
183
|
+
Print the URI of the oldest non-draft PR waiting for your review. If you are not requested for review on any PRs, Harmony will suggest a PR that your review is not requested on.
|
|
203
184
|
|
|
204
185
|
You can skip PRs and retrieve the next-oldest one by passing a dash followed by the number to skip (e.g. `-2` to skip the two oldest waiting PRs).
|
|
205
186
|
|
|
@@ -211,7 +192,7 @@ Many operating systems have an `open` command (though the name "open" is not ubi
|
|
|
211
192
|
|
|
212
193
|
You can also run `harmony contribute --list` if you want to list out a few PRs to consider reviewing them instead of choosing just one PR to look into and printing that PRs URI.
|
|
213
194
|
|
|
214
|
-
|
|
195
|
+
### Examples
|
|
215
196
|
Retrieve a URI for the oldest unreviewed and open PR (prioritizing PRs for which you are a requested reviewer):
|
|
216
197
|
```shell
|
|
217
198
|
harmony contribute
|
|
@@ -237,31 +218,106 @@ Permanently ignore a PR by its number:
|
|
|
237
218
|
harmony contribute --ignore 1234
|
|
238
219
|
```
|
|
239
220
|
|
|
240
|
-
|
|
241
|
-
|
|
221
|
+
## `graph [--completed] {team-slug}`
|
|
222
|
+
Graph the relative review workload of each of the members of the given GitHub Team.
|
|
242
223
|
|
|
243
|
-
|
|
244
|
-
Running `harmony reflect` will show a summary of your review requests and authored pull requests.
|
|
224
|
+
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.
|
|
245
225
|
|
|
246
|
-
|
|
226
|
+
## `health`
|
|
227
|
+
Graph all open PRs grouped by the month when each was created.
|
|
228
|
+
|
|
229
|
+
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.
|
|
230
|
+
|
|
231
|
+
|
|
232
|
+
|
|
233
|
+
## `help [subcommand]`
|
|
234
|
+
Print help.
|
|
235
|
+
|
|
236
|
+
## `label {label} [...]`
|
|
237
|
+
Helps you create a PR if one does not exist yet and then it will apply the given labels to the PR. This is essentially an alias for the `harmony pr` command but without support for creating draft PRs.
|
|
238
|
+
|
|
239
|
+
Note that labels are _not_ prefixed with '#' for this command. There is no need to differentiate labels from other kinds of arguments to `harmony label`.
|
|
247
240
|
|
|
248
|
-
|
|
241
|
+
## `list [team-slug]`
|
|
249
242
|
Running `harmony list` will list all the teams for the configured GitHub organization.
|
|
250
243
|
|
|
251
244
|
Running `harmony list <team>` will list the members of the given GitHub Team.
|
|
252
245
|
|
|
253
|
-
|
|
254
|
-
|
|
246
|
+
## `pr [--draft] [#label, ...]`
|
|
247
|
+
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.
|
|
255
248
|
|
|
256
|
-
|
|
249
|
+
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.
|
|
257
250
|
|
|
258
|
-
|
|
259
|
-
Running `harmony health` will graph all open PRs grouped by the month when each was created.
|
|
251
|
+
You can also specify any number of labels to apply by prefixing them with '#'. For example, `harmony pr #backport #bugfix` would create a PR and apply the `backport` and `bugfix` labels.
|
|
260
252
|
|
|
261
|
-
|
|
253
|
+
If you are using harmony from a script or some other environment without TTY support, harmony will print a GitHub URL that can be used to create the PR. This mode of operation will ignore the `--draft` and `#label` options.
|
|
254
|
+
|
|
255
|
+
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.
|
|
256
|
+
|
|
257
|
+
### Examples
|
|
258
|
+
Create a draft pull request for the current branch:
|
|
259
|
+
```shell
|
|
260
|
+
harmony pr --draft
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
Create a PR for the current branch and add the `urgent` label:
|
|
264
|
+
```shell
|
|
265
|
+
harmony pr #urgent
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
## `quick`
|
|
269
|
+
Helps you create a new GitHub issue and a branch to
|
|
270
|
+
work on that issue all in one go. The branch name will be structured such that
|
|
271
|
+
if you have GitHub branch parsing on then the PR you create for the branch later
|
|
272
|
+
on will refer to the issue created now.
|
|
273
|
+
|
|
274
|
+
## `reflect`
|
|
275
|
+
Show a summary of your review requests and authored pull requests.
|
|
276
|
+
|
|
277
|
+
|
|
278
|
+
|
|
279
|
+
## `request {team-slug | +user-login} [options]`
|
|
280
|
+
Helps you create a PR if one does not exist yet and then it will request reviews from teams and/or users.
|
|
281
|
+
|
|
282
|
+
There is also a `harmony rq` alias for `harmony request`.
|
|
283
|
+
|
|
284
|
+
If `harmony config requestUsers` is `True` (defualt) then harmony will pick someone to review the PR (from one of the listed teams). If `harmony config requestTeams` is `True` (default) then harmony will request reviews from the teams you listed. If `harmony config commentOnRequest` is `True` then harmony will comment on the Pull Request indicating that teams & users were "harmoniously requested" -- this comment will @mention requested users so it may be useful or annoying depending on the requested user's GitHub notification settings.
|
|
285
|
+
|
|
286
|
+
You can also require that specific additional users (on top of the one Harmony will pick for you) are requested to review the PR. You do this by specifying those users' logins prefixed with '+' as arguments to Harmony. This will request review from those specific additional users regardless of the `requestUsers` setting; that setting controls whether Harmony picks users from each Team you specify to review PRs.
|
|
287
|
+
|
|
288
|
+
You can optionally apply any number of labels to the PR at the same time as requesting reviewers by prefixing the labels with '#'.
|
|
289
|
+
|
|
290
|
+
### Deferring to GitHub
|
|
291
|
+
If your team has GitHub set up to auto-request reviews from 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 request a team but not also pick an individual from that team:
|
|
292
|
+
```shell
|
|
293
|
+
harmony config requestTeams true
|
|
294
|
+
harmony config requestUsers false
|
|
295
|
+
```
|
|
296
|
+
This does not prevent you from requesting specific individuals with the `+<user>` syntax described above.
|
|
297
|
+
|
|
298
|
+
### Examples
|
|
299
|
+
Request review from the most available reviewer from the "developers" GitHub Team:
|
|
300
|
+
```shell
|
|
301
|
+
harmony request developers
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
Request review from the most available reviewer from either the "frontend" or "backend" GitHub Team:
|
|
305
|
+
```shell
|
|
306
|
+
harmony request frontend backend
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
Request review from the most available reviewer from the "web" team and additionally request review from the users with logins "carl001" and "emmaham":
|
|
310
|
+
```shell
|
|
311
|
+
harmony request web +carl001 +emmaham
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
## `sync`
|
|
315
|
+
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.
|
|
316
|
+
|
|
317
|
+
## `version`
|
|
318
|
+
Print Harmony's version.
|
|
262
319
|
|
|
263
|
-
|
|
264
320
|
|
|
265
|
-
|
|
266
|
-
|
|
321
|
+
## `whoami`
|
|
322
|
+
Print information about the currently configured and authenticated user.
|
|
267
323
|
|