@mattpolzin/harmony 5.5.0 → 5.5.1

package/man/harmony.1

@@ -0,0 +1,511 @@
+.\" Automatically generated by Pandoc 3.7.0.2
+.\"
+.TH "harmony" "1" "" "Version 5.5.1" "Harmony User\(cqs Guide"
+.SH NAME
+Harmony \- Harmonize with coworkers around GitHub reviewing
+.SH SYNOPSIS
+\f[CR]harmony branch\f[R]
+.PD 0
+.P
+.PD
+\f[CR]harmony config {property} [value]\f[R]
+.PD 0
+.P
+.PD
+\f[CR]harmony contribute [options] {uri | pr\-number}\f[R]
+.PD 0
+.P
+.PD
+\f[CR]harmony graph [options] {team\-slug}\f[R]
+.PD 0
+.P
+.PD
+\f[CR]harmony health\f[R]
+.PD 0
+.P
+.PD
+\f[CR]harmony help [subcommand]\f[R]
+.PD 0
+.P
+.PD
+\f[CR]harmony label {label} [...]\f[R]
+.PD 0
+.P
+.PD
+\f[CR]harmony list [team\-slug]\f[R]
+.PD 0
+.P
+.PD
+\f[CR]harmony pr [options]\f[R]
+.PD 0
+.P
+.PD
+\f[CR]harmony quick\f[R]
+.PD 0
+.P
+.PD
+\f[CR]harmony reflect\f[R]
+.PD 0
+.P
+.PD
+\f[CR]harmony request {team\-slug | +user\-login} [options]\f[R]
+.PD 0
+.P
+.PD
+\f[CR]harmony rq {team\-slug | +user\-login} [options]\f[R]
+.PD 0
+.P
+.PD
+\f[CR]harmony sync\f[R]
+.PD 0
+.P
+.PD
+\f[CR]harmony version\f[R]
+.PD 0
+.P
+.PD
+\f[CR]harmony whoami\f[R]
+.SH DESCRIPTION
+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.
+.PP
+Harmony offers a heuristic for PR review requests that is different than
+GitHub\(cqs round robin or weighted algorithms, but Harmony can also
+work well even if your team uses GitHub\(cqs automatic PR review
+requests (see below).
+.SS Dependencies
+.SS Runtime
+Running Harmony requires NodeJS 18+ (and a local installation of
+\f[CR]git\f[R]) or alternatively Nix with flakes enabled.
+.PP
+If you\(cqd like to try Harmony out without even \(lqinstalling\(rq it
+and you have Nix installed with flakes enabled, you can run it as
+\f[CR]nix run github:mattpolzin/harmony\f[R].
+.SS 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.
+.PP
+Alternatively, you can build Harmony with Docker (see Docker Build).
+.SS Installation
+For any installation, you need to have a GitHub \c
+.UR https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token
+Personal Access Token
+.UE \c
+\&.
+.PP
+Your Personal Access Token should have the following permissions: \-
+\f[CR]repo\f[R] (Full control of private repositories) \-
+\f[CR]read:org\f[R] (Read org and team membership, read org projects) \-
+\f[CR]read:user\f[R] \- \f[CR]user:email\f[R] \-
+\f[CR]read:discussion\f[R] \- \f[CR]read:enterprise\f[R] (Read
+enterprise profile data)
+.PP
+You can either add the PAT to your environment as the
+\f[CR]GITHUB_PAT\f[R] (or alternatively \f[CR]GH_TOKEN\f[R]) variable
+(perhaps exporting it from your shell resource file or profile) or you
+can store your PAT in Harmony\(cqs config file.
+The first time you start Harmony, it will ask you to configure your PAT
+if you don\(cqt 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.
+.SS NPM
+You can install Harmony via npm directly by running
+\f[CR]npm install \-g \(atmattpolzin/harmony\f[R].
+.SS GitHub Release
+You can install any Harmony release by downloading the
+\f[CR]harmony\-npm.tar.gz\f[R] file from the GitHub Release page,
+unzipping it, and running \f[CR]npm install \-\-global\f[R].
+.SS Nix Flake
+You can add Harmony to your Flake inputs as follows:
+.IP
+.EX
+  inputs = {
+    ...
+    harmony.url = \(dqgithub:mattpolzin/harmony\(dq;
+    harmony.inputs.nixpkgs.follows = \(dqnixpkgs\(dq;
+  };
+.EE
+.PP
+Then, in your outputs, bring Harmony into a package install list as
+\f[CR]harmony.packages.<system>.harmony\f[R].
+.PP
+Harmony builds are cached in Cachix so you can take advantage of those
+builds by adding \f[CR]https://gh\-harmony.cachix.org\f[R] to the list
+of \f[CR]substituters\f[R] and
+\f[CR]gh\-harmony.cachix.org\-1:KX5tTtEt3Y6an8pywe3Cy6jR9bUo+1Cl7hJmh+5eI4I=\f[R]
+to the list of \f[CR]trusted\-public\-keys\f[R].
+.SS From Source
+The build script assumes a HEAD build of Idris 2 is installed on your
+system.
+For an alternative, see the Docker Build instructions below.
+.PP
+Build Harmony from source with a call to \f[CR]make\f[R].
+Then install it globally with \f[CR]make install\f[R].
+.SS Docker Build
+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.
+.PP
+First, download the latest nightly Docker image:
+.IP
+.EX
+docker pull mattpolzin2/idris\-docker:nightly
+.EE
+.PP
+Then, from a directory containing this Harmony git repository, build
+Harmony:
+.IP
+.EX
+docker run \-\-rm \-v \(dq$(pwd):/build\(dq \(rs
+  mattpolzin2/idris\-docker:nightly \(rs
+  bash \-c \(dqapt\-get update && apt\-get install \-y git && cd /build && make\(dq
+.EE
+.PP
+At this point you are done with Docker.
+From the same directory, install Harmony globally:
+.IP
+.EX
+npm install \-\-global
+.EE
+.SS Bash completion
+Set up Bash completion by adding the following to your Bash resource
+file or profile:
+.IP
+.EX
+eval \(dq$(harmony \-\-bash\-completion\-script)\(dq
+.EE
+.SS Zsh completion
+Zsh completion is supported via \f[CR]bashcompinit\f[R] and can be
+loaded by adding the following to your Zsh resource file or profile:
+.IP
+.EX
+eval \(dq$(harmony \-\-zsh\-completion\-script)\(dq
+.EE
+.SS Usage
+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 \f[CR]harmony.json\f[R] in
+the current working directory.
+.PP
+Note that the GitHub organization and repository are both slugs, not
+names.
+These are the values you find in a GitHub URL pointing to your
+repository.
+Harmony works with personal repositories but some of Harmony\(cqs
+features are not available for these repos because they do not have
+teams or members.
+.IP
+.EX
+$ harmony sync
+Creating a new configuration (storing in harmony.json)...
+
+Harmony uses a GitHub Personal Access Token (PAT) to communicate with GitHub.
+You can set this via the $GITHUB_PAT or $GH_TOKEN environment variables or a config property.
+If you don\(aqt set in your config now, you can set later with \(gaharmony config githubPAT abcdefg\(ga.
+The ENV var will always take precedence over the config property.
+
+What PAT would you like to set in the config file (ENTER for default: unset)?
+
+What GitHub org would you like to use harmony for (ENTER for default: myorg)?
+
+What repository would you like to use harmony for (ENTER for default: myrepo)?
+
+What GitHub remote repo would you like to use harmony for (ENTER for default: origin)?
+
+Would you like harmony to comment when it requests reviewers? [Y/n] 
+Would you like harmony to request team reviews in addition to individuals when it requests reviewers? [Y/n] 
+Creating config...
+.EE
+.PP
+Once configured, Harmony supports the following commands:
+\f[CR]config\f[R], \f[CR]branch\f[R], \f[CR]pr\f[R], \f[CR]quick\f[R],
+\f[CR]label\f[R], \f[CR]request\f[R] (also aliased to \f[CR]rq\f[R]),
+\f[CR]contribute\f[R], \f[CR]whoami\f[R], \f[CR]reflect\f[R],
+\f[CR]list\f[R], \f[CR]graph\f[R], \f[CR]health\f[R], and
+\f[CR]sync\f[R].
+.PP
+\f[B]Note on color output:\f[R] Harmony uses colored output for some
+commands.
+You can adjust these colors slightly with the \f[CR]theme\f[R]
+configuration option.
+You can also use the \f[CR]NO_COLOR\f[R] environment variable to disable
+all colored output.
+Lastly, Harmony will avoid colored output when it determines
+\f[CR]stdout\f[R] is not a TTY device (as is the case for
+e.g.\ redirecting harmony output into a file or piping into
+\f[CR]cat\f[R]: \f[CR]harmony ... | cat\f[R]).
+.SH SUBCOMMANDS
+.SS \f[CR]branch\f[R]
+Print the URI for accessing the currently checked out branch on GitHub.
+.PP
+Many operating systems have an \f[CR]open\f[R] command (though the name
+\(lqopen\(rq is not ubiquitous); this means you can run something like
+\f[CR]open $(harmony branch)\f[R] to open a web browser to the current
+branch on GitHub.
+.SS \f[CR]config {property} [value]\f[R]
+Read the given configuration property.
+\f[CR]harmony config <property> <value>\f[R] will set the configuration
+property.
+.PP
+Not all configuration properties can be read/set with this command.
+.SS Properties
+.TP
+\f[CR]requestTeams\f[R] (\f[CR]true\f[R]/\f[CR]false\f[R])
+When picking a reviewer from a team, request the team as a reviewer as
+well.
+.TP
+\f[CR]requestUsers\f[R] (\f[CR]true\f[R]/\f[CR]false\f[R])
+When requesting a team as a reviewer, pick a user to review as well.
+.TP
+\f[CR]commentOnRequest\f[R] (\f[CR]none\f[R]/\f[CR]name\f[R]/\f[CR]at\-mention\f[R])
+When requesting a reviewer chosen by Harmony, comment on the pull
+request or not.
+.TP
+\f[CR]branchParsing\f[R] (\f[CR]none\f[R]/\f[CR]jira\f[R]/\f[CR]github\f[R])
+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.
+.TP
+\f[CR]defaultRemote\f[R] (optional string)
+When pushing new branches, what remote destination should be used.
+.TP
+\f[CR]mainBranch\f[R] (optional string)
+When creating a PR, this is the default base branch.
+.TP
+\f[CR]theme\f[R] (\f[CR]dark\f[R]/\f[CR]light\f[R])
+Use colors suited better for either a dark or light Terminal background.
+.TP
+\f[CR]githubPAT\f[R] (optional string)
+If the \f[CR]$GITHUB_PAT\f[R] and \f[CR]$GH_TOKEN\f[R] environment
+variables are not set, this Personal Access Token is used to
+authenticate with GitHub.
+.SS \f[CR]contribute [options]\f[R]
+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.
+.PP
+You can skip PRs and retrieve the next\-oldest one by passing a dash
+followed by the number to skip (e.g.\ \f[CR]\-2\f[R] to skip the two
+oldest waiting PRs).
+.PP
+You can also more permanently ignore a particular PR (perhaps it has
+gone stagnant but your org does not want to close it for whatever
+reason).
+To do this, use the \f[CR]\-\-ignore\f[R] or \f[CR]\-i\f[R] option and
+pass it the GitHub URI or the Pull Request Number of a PR to ignore.
+This PR will be omitted from consideration for the \f[CR]contribute\f[R]
+command from then on.
+This only impacts your local machine where the ignore list is stored in
+Harmony\(cqs config file.
+.PP
+You can simultaneously get the URI for a PR to review and checkout the
+branch needing review by passing the \f[CR]\-\-checkout\f[R] or
+\f[CR]\-c\f[R] option to the \f[CR]contribute\f[R] command.
+.PP
+Many operating systems have an \f[CR]open\f[R] command (though the name
+\(lqopen\(rq is not ubiquitous); this means you can run something like
+\f[CR]open $(harmony contribute)\f[R] to open a web browser to the PR
+that Harmony is suggesting.
+.PP
+You can also run \f[CR]harmony contribute \-\-list\f[R] 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.
+.SS Examples
+Retrieve a URI for the oldest unreviewed and open PR (prioritizing PRs
+for which you are a requested reviewer):
+.IP
+.EX
+harmony contribute
+.EE
+.PP
+Retrieve a URI for a PR to contribute a review, skipping over the first
+3 suggestions:
+.IP
+.EX
+harmony contribute \-3
+.EE
+.PP
+Retrieve a URI for a PR to contribute a review and check the git branch
+out as well:
+.IP
+.EX
+harmony contribute \-\-checkout
+.EE
+.PP
+Permanently ignore a PR by URI:
+.IP
+.EX
+harmony contribute \-\-ignore https://github.com/myorg/myrepo/pull/1234
+.EE
+.PP
+Permanently ignore a PR by its number:
+.IP
+.EX
+harmony contribute \-\-ignore 1234
+.EE
+.SS \f[CR]graph [\-\-completed] {team\-slug}\f[R]
+Graph the relative review workload of each of the members of the given
+GitHub Team.
+.PP
+You can optionally graph completed PR reviews with the
+\f[CR]\-\-completed\f[R] flag as well, though these are not considered
+for Harmony\(cqs weighting algorithm for review workload.
+.SS \f[CR]health\f[R]
+Graph all open PRs grouped by the month when each was created.
+.PP
+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\(cqt yet paid off.
+.SS \f[CR]help [subcommand]\f[R]
+Print help.
+.SS \f[CR]label {label} [...]\f[R]
+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 \f[CR]harmony pr\f[R] command but
+without support for creating draft PRs.
+.PP
+Note that labels are \f[I]not\f[R] prefixed with `#' for this command.
+There is no need to differentiate labels from other kinds of arguments
+to \f[CR]harmony label\f[R].
+.SS \f[CR]list [team\-slug]\f[R]
+Running \f[CR]harmony list\f[R] will list all the teams for the
+configured GitHub organization.
+.PP
+Running \f[CR]harmony list <team>\f[R] will list the members of the
+given GitHub Team.
+.SS \f[CR]pr [\-\-draft] [#label, ...]\f[R]
+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
+\f[CR]\-\-draft\f[R] flag with the \f[CR]pr\f[R] command.
+.PP
+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 \f[CR]EDITOR\f[R] environment variable set, Harmony will
+use that editor to get the PR description from you.
+If you have a PR template at
+\f[CR].github/PULL_REQUEST_TEMPLATE.md\f[R], Harmony will also preload
+that into your editor.
+If you do not have an \f[CR]EDITOR\f[R] environment variable set, you
+will still be able to enter a description from the command line but PR
+templates are only supported when an \f[CR]EDITOR\f[R] is specified.
+.PP
+You can also specify any number of labels to apply by prefixing them
+with `#'.
+For example, \f[CR]harmony pr #backport #bugfix\f[R] would create a PR
+and apply the \f[CR]backport\f[R] and \f[CR]bugfix\f[R] labels.
+.PP
+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 \f[CR]\-\-draft\f[R] and
+\f[CR]#label\f[R] options.
+.PP
+Many operating systems have an \f[CR]open\f[R] command (though the name
+\(lqopen\(rq is not ubiquitous); this means you can run something like
+\f[CR]open $(harmony pr)\f[R] to open a web browser to an existing PR
+for the current branch.
+.SS Examples
+Create a draft pull request for the current branch:
+.IP
+.EX
+harmony pr \-\-draft
+.EE
+.PP
+Create a PR for the current branch and add the \f[CR]urgent\f[R] label:
+.IP
+.EX
+harmony pr #urgent
+.EE
+.SS \f[CR]quick\f[R]
+Helps you create a new GitHub issue and a branch to work on that issue
+all in one go.
+The branch name will be structured such that if you have GitHub branch
+parsing on then the PR you create for the branch later on will refer to
+the issue created now.
+.SS \f[CR]reflect\f[R]
+Show a summary of your review requests and authored pull requests.
+.SS \f[CR]request {team\-slug | +user\-login} [options]\f[R]
+Helps you create a PR if one does not exist yet and then it will request
+reviews from teams and/or users.
+.PP
+There is also a \f[CR]harmony rq\f[R] alias for
+\f[CR]harmony request\f[R].
+.PP
+If \f[CR]harmony config requestUsers\f[R] is \f[CR]True\f[R] (defualt)
+then harmony will pick someone to review the PR (from one of the listed
+teams).
+If \f[CR]harmony config requestTeams\f[R] is \f[CR]True\f[R] (default)
+then harmony will request reviews from the teams you listed.
+If \f[CR]harmony config commentOnRequest\f[R] is \f[CR]True\f[R] then
+harmony will comment on the Pull Request indicating that teams & users
+were \(lqharmoniously requested\(rq \(en this comment will \(atmention
+requested users so it may be useful or annoying depending on the
+requested user\(cqs GitHub notification settings.
+.PP
+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\(cq logins prefixed with `+' as
+arguments to Harmony.
+This will request review from those specific additional users regardless
+of the \f[CR]requestUsers\f[R] setting; that setting controls whether
+Harmony picks users from each Team you specify to review PRs.
+.PP
+You can optionally apply any number of labels to the PR at the same time
+as requesting reviewers by prefixing the labels with `#'.
+.SS Deferring to GitHub
+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 \f[CR]config\f[R] commands to tell harmony to
+request a team but not also pick an individual from that team:
+.IP
+.EX
+harmony config requestTeams true
+harmony config requestUsers false
+.EE
+.PP
+This does not prevent you from requesting specific individuals with the
+\f[CR]+<user>\f[R] syntax described above.
+.SS Examples
+Request review from the most available reviewer from the
+\(lqdevelopers\(rq GitHub Team:
+.IP
+.EX
+harmony request developers
+.EE
+.PP
+Request review from the most available reviewer from either the
+\(lqfrontend\(rq or \(lqbackend\(rq GitHub Team:
+.IP
+.EX
+harmony request frontend backend
+.EE
+.PP
+Request review from the most available reviewer from the \(lqweb\(rq
+team and additionally request review from the users with logins
+\(lqcarl001\(rq and \(lqemmaham\(rq:
+.IP
+.EX
+harmony request web +carl001 +emmaham
+.EE
+.SS \f[CR]sync\f[R]
+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.
+.SS \f[CR]version\f[R]
+Print Harmony\(cqs version.
+.SS \f[CR]whoami\f[R]
+Print information about the currently configured and authenticated user.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mattpolzin/harmony",
-  "version": "5.5.0",
+  "version": "5.5.1",
   "engines": {
     "node": ">=18.0.0"
   },
@@ -23,6 +23,7 @@
   "bin": {
     "harmony": "harmony"
   },
+  "man": "./man/harmony.1",
   "scripts": {},
   "author": "Mathew Polzin",
   "license": "MIT",