@mattpolzin/harmony 5.5.0 → 5.6.0
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 +286 -122
- package/harmony +826 -666
- package/man/harmony.1 +515 -0
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -1,22 +1,56 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
1
|
+
% harmony(1) Version 5.6.0 | 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
|
|
25
|
+
Harmony is a small tool that helps teams keep GitHub reviews running smoothly.
|
|
26
|
+
It takes the work out of picking someone from a pool of developers to review a
|
|
27
|
+
new PR. Harmony does this by heuristically determining who on a particular
|
|
28
|
+
GitHub Team has the least current/recent review workload.
|
|
29
|
+
|
|
30
|
+
Harmony offers a heuristic for PR review requests that is different than
|
|
31
|
+
GitHub's round robin or weighted algorithms, but Harmony can also work well even
|
|
32
|
+
if your team uses GitHub's automatic PR review requests ([see below](#deferring-to-github)).
|
|
6
33
|
|
|
7
34
|
## Dependencies
|
|
8
35
|
### Runtime
|
|
9
|
-
Running Harmony requires NodeJS 18+ (and a local installation of `git`) or
|
|
36
|
+
Running Harmony requires NodeJS 18+ (and a local installation of `git`) or
|
|
37
|
+
alternatively Nix with flakes enabled.
|
|
10
38
|
|
|
11
|
-
If you'd like to try Harmony out without even "installing" it and you have Nix
|
|
39
|
+
If you'd like to try Harmony out without even "installing" it and you have Nix
|
|
40
|
+
installed with flakes enabled, you can run it as
|
|
41
|
+
`nix run github:mattpolzin/harmony`.
|
|
12
42
|
|
|
13
43
|
### Build time
|
|
14
|
-
Building the latest commits of Harmony requires a HEAD build of the Idris 2
|
|
44
|
+
Building the latest commits of Harmony requires a HEAD build of the Idris 2
|
|
45
|
+
compiler. Each release page also indicates the version of Idris 2 that
|
|
46
|
+
particular release will build against.
|
|
15
47
|
|
|
16
|
-
Alternatively, you can build Harmony with Docker (see
|
|
48
|
+
Alternatively, you can build Harmony with Docker (see
|
|
49
|
+
[Docker Build](#docker-build)).
|
|
17
50
|
|
|
18
51
|
## Installation
|
|
19
|
-
For any installation, you need to have a GitHub
|
|
52
|
+
For any installation, you need to have a GitHub
|
|
53
|
+
[Personal Access Token](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token).
|
|
20
54
|
|
|
21
55
|
Your Personal Access Token should have the following permissions:
|
|
22
56
|
- `repo` (Full control of private repositories)
|
|
@@ -26,13 +60,21 @@ Your Personal Access Token should have the following permissions:
|
|
|
26
60
|
- `read:discussion`
|
|
27
61
|
- `read:enterprise` (Read enterprise profile data)
|
|
28
62
|
|
|
29
|
-
You can either add the PAT to your environment as the `GITHUB_PAT` (or
|
|
63
|
+
You can either add the PAT to your environment as the `GITHUB_PAT` (or
|
|
64
|
+
alternatively `GH_TOKEN`) variable (perhaps exporting it from your shell
|
|
65
|
+
resource file or profile) or you can store your PAT in Harmony's config file.
|
|
66
|
+
The first time you start Harmony, it will ask you to configure your PAT if you
|
|
67
|
+
don't want to use the Environment variable. You only need one of (a) the ENV var
|
|
68
|
+
and (b) the config property and the environment variable will take precedence if
|
|
69
|
+
you have both set.
|
|
30
70
|
|
|
31
71
|
### NPM
|
|
32
|
-
You can install Harmony via npm directly by running
|
|
72
|
+
You can install Harmony via npm directly by running
|
|
73
|
+
`npm install -g @mattpolzin/harmony`.
|
|
33
74
|
|
|
34
75
|
### GitHub Release
|
|
35
|
-
You can install any Harmony release by downloading the `harmony-npm.tar.gz` file
|
|
76
|
+
You can install any Harmony release by downloading the `harmony-npm.tar.gz` file
|
|
77
|
+
from the GitHub Release page, unzipping it, and running `npm install --global`.
|
|
36
78
|
|
|
37
79
|
### Nix Flake
|
|
38
80
|
You can add Harmony to your Flake inputs as follows:
|
|
@@ -44,7 +86,8 @@ You can add Harmony to your Flake inputs as follows:
|
|
|
44
86
|
};
|
|
45
87
|
```
|
|
46
88
|
|
|
47
|
-
Then, in your outputs, bring Harmony into a package install list as
|
|
89
|
+
Then, in your outputs, bring Harmony into a package install list as
|
|
90
|
+
`harmony.packages.<system>.harmony`.
|
|
48
91
|
|
|
49
92
|
Harmony builds are cached in Cachix so you can take advantage of those builds by
|
|
50
93
|
adding `https://gh-harmony.cachix.org` to the list of `substituters` and
|
|
@@ -52,12 +95,16 @@ adding `https://gh-harmony.cachix.org` to the list of `substituters` and
|
|
|
52
95
|
list of `trusted-public-keys`.
|
|
53
96
|
|
|
54
97
|
### From Source
|
|
55
|
-
The build script assumes a HEAD build of Idris 2 is installed on your system.
|
|
98
|
+
The build script assumes a HEAD build of Idris 2 is installed on your system.
|
|
99
|
+
For an alternative, see the [Docker Build](#docker-build) instructions below.
|
|
56
100
|
|
|
57
|
-
Build Harmony from source with a call to `make`. Then install it globally with
|
|
101
|
+
Build Harmony from source with a call to `make`. Then install it globally with
|
|
102
|
+
`make install`.
|
|
58
103
|
|
|
59
|
-
|
|
60
|
-
If you want to build Harmony without installing Idris 2 on your system, you can
|
|
104
|
+
### Docker Build
|
|
105
|
+
If you want to build Harmony without installing Idris 2 on your system, you can
|
|
106
|
+
build Harmony within a Docker container and then install the resulting
|
|
107
|
+
Javascript onto your system.
|
|
61
108
|
|
|
62
109
|
First, download the latest nightly Docker image:
|
|
63
110
|
```shell
|
|
@@ -66,30 +113,41 @@ docker pull mattpolzin2/idris-docker:nightly
|
|
|
66
113
|
|
|
67
114
|
Then, from a directory containing this Harmony git repository, build Harmony:
|
|
68
115
|
```shell
|
|
69
|
-
docker run --rm -v "$(pwd):/build"
|
|
116
|
+
docker run --rm -v "$(pwd):/build" \
|
|
117
|
+
mattpolzin2/idris-docker:nightly \
|
|
118
|
+
bash -c "apt-get update && apt-get install -y git && cd /build && make"
|
|
70
119
|
```
|
|
71
120
|
|
|
72
|
-
At this point you are done with Docker. From the same directory, install Harmony
|
|
121
|
+
At this point you are done with Docker. From the same directory, install Harmony
|
|
122
|
+
globally:
|
|
73
123
|
```shell
|
|
74
124
|
npm install --global
|
|
75
125
|
```
|
|
76
126
|
|
|
77
127
|
### Bash completion
|
|
78
|
-
Set up Bash completion by adding the following to your Bash resource file or
|
|
128
|
+
Set up Bash completion by adding the following to your Bash resource file or
|
|
129
|
+
profile:
|
|
79
130
|
```shell
|
|
80
131
|
eval "$(harmony --bash-completion-script)"
|
|
81
132
|
```
|
|
82
133
|
|
|
83
134
|
### Zsh completion
|
|
84
|
-
Zsh completion is supported via `bashcompinit` and can be loaded by adding the
|
|
135
|
+
Zsh completion is supported via `bashcompinit` and can be loaded by adding the
|
|
136
|
+
following to your Zsh resource file or profile:
|
|
85
137
|
```shell
|
|
86
138
|
eval "$(harmony --zsh-completion-script)"
|
|
87
139
|
```
|
|
88
140
|
|
|
89
141
|
## Usage
|
|
90
|
-
The first time you start Harmony in any particular folder, you will be asked to
|
|
91
|
-
|
|
92
|
-
|
|
142
|
+
The first time you start Harmony in any particular folder, you will be asked to
|
|
143
|
+
provide some information about the GitHub repository you are working with. This
|
|
144
|
+
information is stored in a file named `harmony.json` in the current working
|
|
145
|
+
directory.
|
|
146
|
+
|
|
147
|
+
Note that the GitHub organization and repository are both slugs, not names.
|
|
148
|
+
These are the values you find in a GitHub URL pointing to your repository.
|
|
149
|
+
Harmony works with personal repositories but some of Harmony's features are not
|
|
150
|
+
available for these repos because they do not have teams or members.
|
|
93
151
|
```
|
|
94
152
|
$ harmony sync
|
|
95
153
|
Creating a new configuration (storing in harmony.json)...
|
|
@@ -112,161 +170,267 @@ Would you like harmony to request team reviews in addition to individuals when i
|
|
|
112
170
|
Creating config...
|
|
113
171
|
```
|
|
114
172
|
|
|
115
|
-
Once configured, Harmony supports the following commands: `config`, `branch`,
|
|
173
|
+
Once configured, Harmony supports the following commands: `config`, `branch`,
|
|
174
|
+
`pr`, `quick`, `label`, `request` (also aliased to `rq`), `contribute`,
|
|
175
|
+
`whoami`, `reflect`, `list`, `graph`, `health`, and `sync`.
|
|
116
176
|
|
|
117
177
|
**Note on color output:**
|
|
118
|
-
Harmony uses colored output for some commands. You can adjust these colors
|
|
178
|
+
Harmony uses colored output for some commands. You can adjust these colors
|
|
179
|
+
slightly with the `theme` configuration option. You can also use the `NO_COLOR`
|
|
180
|
+
environment variable to disable all colored output. Lastly, Harmony will avoid
|
|
181
|
+
colored output when it determines `stdout` is not a TTY device (as is the case
|
|
182
|
+
for e.g. redirecting harmony output into a file or piping into `cat`:
|
|
183
|
+
`harmony ... | cat`).
|
|
184
|
+
|
|
185
|
+
# SUBCOMMANDS
|
|
186
|
+
|
|
187
|
+
## `branch`
|
|
188
|
+
Print the URI for accessing the currently checked out branch on GitHub.
|
|
119
189
|
|
|
120
|
-
|
|
121
|
-
|
|
190
|
+
Many operating systems have an `open` command (though the name "open" is not
|
|
191
|
+
ubiquitous); this means you can run something like `open $(harmony branch)` to
|
|
192
|
+
open a web browser to the current branch on GitHub.
|
|
193
|
+
|
|
194
|
+
## `config {property} [value]`
|
|
195
|
+
Read the given configuration property. `harmony config <property> <value>` will
|
|
196
|
+
set the configuration property.
|
|
122
197
|
|
|
123
198
|
Not all configuration properties can be read/set with this command.
|
|
124
|
-
#### Properties
|
|
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
199
|
|
|
134
|
-
###
|
|
135
|
-
Running `harmony branch` will print the URI for accessing the currently checked out branch on GitHub.
|
|
200
|
+
### Properties
|
|
136
201
|
|
|
137
|
-
|
|
202
|
+
`requestTeams` (`true`/`false`)
|
|
203
|
+
: When picking a reviewer from a team, request the team as a reviewer as well.
|
|
138
204
|
|
|
139
|
-
|
|
140
|
-
|
|
205
|
+
`requestUsers` (`true`/`false`)
|
|
206
|
+
: When requesting a team as a reviewer, pick a user to review as well.
|
|
141
207
|
|
|
142
|
-
|
|
208
|
+
`commentOnRequest` (`none`/`name`/`at-mention`)
|
|
209
|
+
: When requesting a reviewer chosen by Harmony, comment on the pull request or not.
|
|
143
210
|
|
|
144
|
-
|
|
211
|
+
`branchParsing` (`none`/`jira`/`github`)
|
|
212
|
+
: 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.
|
|
145
213
|
|
|
146
|
-
|
|
214
|
+
`defaultRemote` (optional string)
|
|
215
|
+
: When pushing new branches, what remote destination should be used.
|
|
147
216
|
|
|
148
|
-
|
|
217
|
+
`mainBranch` (optional string)
|
|
218
|
+
: When creating a PR, this is the default base branch.
|
|
149
219
|
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
```shell
|
|
153
|
-
harmony pr --draft
|
|
154
|
-
```
|
|
220
|
+
`theme` (`dark`/`light`)
|
|
221
|
+
: Use colors suited better for either a dark or light Terminal background.
|
|
155
222
|
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
harmony pr #urgent
|
|
159
|
-
```
|
|
160
|
-
### Quick
|
|
161
|
-
Running `harmony quick` will help you create a new GitHub issue and a branch to
|
|
162
|
-
work on that issue all in one go. The branch name will be structured such that
|
|
163
|
-
if you have GitHub branch parsing on then the PR you create for the branch later
|
|
164
|
-
on will refer to the issue created now.
|
|
223
|
+
`githubPAT` (optional string)
|
|
224
|
+
: If the `$GITHUB_PAT` and `$GH_TOKEN` environment variables are not set, this Personal Access Token is used to authenticate with GitHub.
|
|
165
225
|
|
|
166
|
-
|
|
167
|
-
|
|
226
|
+
## `contribute [options]`
|
|
227
|
+
Print the URI of the oldest non-draft PR waiting for your review. If you are not
|
|
228
|
+
requested for review on any PRs, Harmony will suggest a PR that your review is
|
|
229
|
+
not requested on.
|
|
168
230
|
|
|
169
|
-
|
|
231
|
+
You can skip PRs and retrieve the next-oldest one by passing a dash followed by
|
|
232
|
+
the number to skip (e.g. `-2` to skip the two oldest waiting PRs).
|
|
170
233
|
|
|
171
|
-
|
|
172
|
-
|
|
234
|
+
You can also more permanently ignore a particular PR (perhaps it has gone
|
|
235
|
+
stagnant but your org does not want to close it for whatever reason). To do
|
|
236
|
+
this, use the `--ignore` or `-i` option and pass it the GitHub URI or the Pull
|
|
237
|
+
Request Number of a PR to ignore. This PR will be omitted from consideration for
|
|
238
|
+
the `contribute` command from then on. This only impacts your local machine
|
|
239
|
+
where the ignore list is stored in Harmony's config file.
|
|
173
240
|
|
|
174
|
-
|
|
241
|
+
You can simultaneously get the URI for a PR to review and checkout the branch
|
|
242
|
+
needing review by passing the `--checkout` or `-c` option to the `contribute`
|
|
243
|
+
command.
|
|
175
244
|
|
|
176
|
-
|
|
245
|
+
Many operating systems have an `open` command (though the name "open" is not
|
|
246
|
+
ubiquitous); this means you can run something like `open $(harmony contribute)`
|
|
247
|
+
to open a web browser to the PR that Harmony is suggesting.
|
|
177
248
|
|
|
178
|
-
You can also
|
|
249
|
+
You can also run `harmony contribute --list` if you want to list out a few PRs
|
|
250
|
+
to consider reviewing them instead of choosing just one PR to look into and
|
|
251
|
+
printing that PRs URI.
|
|
179
252
|
|
|
180
|
-
|
|
253
|
+
### Examples
|
|
254
|
+
Retrieve a URI for the oldest unreviewed and open PR (prioritizing PRs for which
|
|
255
|
+
you are a requested reviewer):
|
|
256
|
+
```shell
|
|
257
|
+
harmony contribute
|
|
258
|
+
```
|
|
181
259
|
|
|
182
|
-
|
|
183
|
-
|
|
260
|
+
Retrieve a URI for a PR to contribute a review, skipping over the first 3
|
|
261
|
+
suggestions:
|
|
184
262
|
```shell
|
|
185
|
-
harmony
|
|
186
|
-
harmony config requestUsers false
|
|
263
|
+
harmony contribute -3
|
|
187
264
|
```
|
|
188
|
-
This does not prevent you from requesting specific individuals with the `+<user>` syntax described above.
|
|
189
265
|
|
|
190
|
-
|
|
191
|
-
|
|
266
|
+
Retrieve a URI for a PR to contribute a review and check the git branch out as
|
|
267
|
+
well:
|
|
192
268
|
```shell
|
|
193
|
-
harmony
|
|
269
|
+
harmony contribute --checkout
|
|
194
270
|
```
|
|
195
271
|
|
|
196
|
-
|
|
272
|
+
Permanently ignore a PR by URI:
|
|
197
273
|
```shell
|
|
198
|
-
harmony
|
|
274
|
+
harmony contribute --ignore https://github.com/myorg/myrepo/pull/1234
|
|
199
275
|
```
|
|
200
276
|
|
|
201
|
-
|
|
277
|
+
Permanently ignore a PR by its number:
|
|
202
278
|
```shell
|
|
203
|
-
harmony
|
|
279
|
+
harmony contribute --ignore 1234
|
|
204
280
|
```
|
|
205
281
|
|
|
206
|
-
|
|
207
|
-
|
|
282
|
+
## `graph [--completed] {team-slug}`
|
|
283
|
+
Graph the relative review workload of each of the members of the given GitHub
|
|
284
|
+
Team.
|
|
208
285
|
|
|
209
|
-
You can
|
|
286
|
+
You can optionally graph completed PR reviews with the `--completed` flag as
|
|
287
|
+
well, though these are not considered for Harmony's weighting algorithm for
|
|
288
|
+
review workload.
|
|
210
289
|
|
|
211
|
-
|
|
290
|
+
## `health`
|
|
291
|
+
Graph all open PRs grouped by the month when each was created.
|
|
212
292
|
|
|
213
|
-
|
|
293
|
+
The idea is that a healthy repository does not have many old PRs still open
|
|
294
|
+
because those PRs represent effort spent by developers that hasn't yet paid off.
|
|
214
295
|
|
|
215
|
-
|
|
296
|
+
|
|
216
297
|
|
|
217
|
-
|
|
298
|
+
## `help [subcommand]`
|
|
299
|
+
Print help.
|
|
218
300
|
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
```
|
|
301
|
+
## `label {label} [...]`
|
|
302
|
+
Helps you create a PR if one does not exist yet and then it will apply the given
|
|
303
|
+
labels to the PR. This is essentially an alias for the `harmony pr` command but
|
|
304
|
+
without support for creating draft PRs.
|
|
224
305
|
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
harmony contribute -3
|
|
228
|
-
```
|
|
306
|
+
Note that labels are _not_ prefixed with '#' for this command. There is no need
|
|
307
|
+
to differentiate labels from other kinds of arguments to `harmony label`.
|
|
229
308
|
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
```
|
|
309
|
+
## `list [team-slug]`
|
|
310
|
+
Running `harmony list` will list all the teams for the configured GitHub
|
|
311
|
+
organization.
|
|
234
312
|
|
|
235
|
-
|
|
313
|
+
Running `harmony list <team>` will list the members of the given GitHub Team.
|
|
314
|
+
|
|
315
|
+
## `pr [--draft] [#label, ...]`
|
|
316
|
+
With a branch checked out will reach out to GitHub to determine if there is an
|
|
317
|
+
open PR for that branch. If there is a PR, Harmony will print a URI that can be
|
|
318
|
+
used to view the PR. If there is not a PR, Harmony will help you create one. New
|
|
319
|
+
and existing PRs can be marked as drafts by specifying the `--draft` flag with
|
|
320
|
+
the `pr` command.
|
|
321
|
+
|
|
322
|
+
If you need to create a PR still, you will be prompted for a branch to open the
|
|
323
|
+
PR against (merge into, eventually), a title for the PR, and a description for
|
|
324
|
+
the PR. If you have an `EDITOR` environment variable set, Harmony will use that
|
|
325
|
+
editor to get the PR description from you. If you have a PR template at
|
|
326
|
+
`.github/PULL_REQUEST_TEMPLATE.md`, Harmony will also preload that into your
|
|
327
|
+
editor. If you do not have an `EDITOR` environment variable set, you will still
|
|
328
|
+
be able to enter a description from the command line but PR templates are only
|
|
329
|
+
supported when an `EDITOR` is specified.
|
|
330
|
+
|
|
331
|
+
You can also specify any number of labels to apply by prefixing them with '#'.
|
|
332
|
+
For example, `harmony pr #backport #bugfix` would create a PR and apply the
|
|
333
|
+
`backport` and `bugfix` labels.
|
|
334
|
+
|
|
335
|
+
If you are using harmony from a script or some other environment without TTY
|
|
336
|
+
support, harmony will print a GitHub URL that can be used to create the PR. This
|
|
337
|
+
mode of operation will ignore the `--draft` and `#label` options.
|
|
338
|
+
|
|
339
|
+
Many operating systems have an `open` command (though the name "open" is not
|
|
340
|
+
ubiquitous); this means you can run something like `open $(harmony pr)` to open
|
|
341
|
+
a web browser to an existing PR for the current branch.
|
|
342
|
+
|
|
343
|
+
### Examples
|
|
344
|
+
Create a draft pull request for the current branch:
|
|
236
345
|
```shell
|
|
237
|
-
harmony
|
|
346
|
+
harmony pr --draft
|
|
238
347
|
```
|
|
239
348
|
|
|
240
|
-
|
|
349
|
+
Create a PR for the current branch and add the `urgent` label:
|
|
241
350
|
```shell
|
|
242
|
-
harmony
|
|
351
|
+
harmony pr #urgent
|
|
243
352
|
```
|
|
244
353
|
|
|
245
|
-
|
|
246
|
-
|
|
354
|
+
## `quick [--bugfix]`
|
|
355
|
+
Helps you create a new GitHub issue and a branch to work on that issue all in
|
|
356
|
+
one go. The branch name will be structured such that if you have GitHub branch
|
|
357
|
+
parsing on then the PR you create for the branch later on will refer to the
|
|
358
|
+
issue created now.
|
|
247
359
|
|
|
248
|
-
|
|
249
|
-
|
|
360
|
+
By default the branch created will be prefixed with `feature` but if you specify
|
|
361
|
+
the `--bugfix` flag then the branch's prefix will be `bugfix`.
|
|
362
|
+
|
|
363
|
+
## `reflect`
|
|
364
|
+
Show a summary of your review requests and authored pull requests.
|
|
250
365
|
|
|
251
366
|
|
|
252
367
|
|
|
253
|
-
|
|
254
|
-
|
|
368
|
+
## `request {team-slug | +user-login} [options]`
|
|
369
|
+
Helps you create a PR if one does not exist yet and then it will request reviews
|
|
370
|
+
from teams and/or users.
|
|
255
371
|
|
|
256
|
-
|
|
372
|
+
There is also a `harmony rq` alias for `harmony request`.
|
|
257
373
|
|
|
258
|
-
|
|
259
|
-
|
|
374
|
+
If `harmony config requestUsers` is `True` (defualt) then harmony will pick
|
|
375
|
+
someone to review the PR (from one of the listed teams). If `harmony config
|
|
376
|
+
requestTeams` is `True` (default) then harmony will request reviews from the
|
|
377
|
+
teams you listed. If `harmony config commentOnRequest` is `True` then harmony
|
|
378
|
+
will comment on the Pull Request indicating that teams & users were
|
|
379
|
+
"harmoniously requested" -- this comment will @mention requested users so it may
|
|
380
|
+
be useful or annoying depending on the requested user's GitHub notification
|
|
381
|
+
settings.
|
|
382
|
+
|
|
383
|
+
You can also require that specific additional users (on top of the one Harmony
|
|
384
|
+
will pick for you) are requested to review the PR. You do this by specifying
|
|
385
|
+
those users' logins prefixed with '+' as arguments to Harmony. This will request
|
|
386
|
+
review from those specific additional users regardless of the `requestUsers`
|
|
387
|
+
setting; that setting controls whether Harmony picks users from each Team you
|
|
388
|
+
specify to review PRs.
|
|
389
|
+
|
|
390
|
+
You can optionally apply any number of labels to the PR at the same time as
|
|
391
|
+
requesting reviewers by prefixing the labels with '#'.
|
|
392
|
+
|
|
393
|
+
### Deferring to GitHub
|
|
394
|
+
If your team has GitHub set up to auto-request reviews from individuals when a
|
|
395
|
+
team is requested for review, you probably want to tell harmony not to also pick
|
|
396
|
+
someone using its heuristics. You can run the following `config` commands to
|
|
397
|
+
tell harmony to request a team but not also pick an individual from that team:
|
|
398
|
+
```shell
|
|
399
|
+
harmony config requestTeams true
|
|
400
|
+
harmony config requestUsers false
|
|
401
|
+
```
|
|
402
|
+
This does not prevent you from requesting specific individuals with the
|
|
403
|
+
`+<user>` syntax described above.
|
|
260
404
|
|
|
261
|
-
|
|
405
|
+
### Examples
|
|
406
|
+
Request review from the most available reviewer from the "developers" GitHub
|
|
407
|
+
Team:
|
|
408
|
+
```shell
|
|
409
|
+
harmony request developers
|
|
410
|
+
```
|
|
262
411
|
|
|
263
|
-
|
|
264
|
-
|
|
412
|
+
Request review from the most available reviewer from either the "frontend" or
|
|
413
|
+
"backend" GitHub Team:
|
|
414
|
+
```shell
|
|
415
|
+
harmony request frontend backend
|
|
416
|
+
```
|
|
417
|
+
|
|
418
|
+
Request review from the most available reviewer from the "web" team and
|
|
419
|
+
additionally request review from the users with logins "carl001" and "emmaham":
|
|
420
|
+
```shell
|
|
421
|
+
harmony request web +carl001 +emmaham
|
|
422
|
+
```
|
|
265
423
|
|
|
266
|
-
|
|
424
|
+
## `sync`
|
|
425
|
+
Sync the locally configured team slugs and user logins that are used by
|
|
426
|
+
auto-completion for Harmony. This sync is also performed automatically the first
|
|
427
|
+
time you run Harmony after more than a day without the configuration being
|
|
428
|
+
synced.
|
|
429
|
+
|
|
430
|
+
## `version`
|
|
431
|
+
Print Harmony's version.
|
|
267
432
|
|
|
268
|
-
|
|
269
433
|
|
|
270
|
-
|
|
271
|
-
|
|
434
|
+
## `whoami`
|
|
435
|
+
Print information about the currently configured and authenticated user.
|
|
272
436
|
|