pot

A CLI to instantly get an overview of a repo's PRs, and decide which PR to act upon next.

pot stands for Pr Overview Tool

How it works

pot creates accumulated data for users concerning one repository, using github's graphql api.

Installation

$ git clone https://github.com/ioanniswd/pot
$ cd pot

$ gem build pot.gemspec
$ gem install --local pot

Usage

Note: Since github needs a personal access token, this token must be accessible to pot, like so for example:

$ GAT=<your_token> pot <options, etc>

Or better yet:

$ GAT=`cat pat/to/token/file` pot <options, etc>

(GAT -> Github Access Token)

In the usage examples following, GAT assignment will not be prefixed for simplicity.

Multiple user overview

$ pot --users=john,jane,doe

User                  | Authored | Reviewing | Actionable PRs | Untouched PRs
-----------------------------------------------------------------------------
john                           2           1                3               0
jane                           1           2                2               0
doe                            3           0                1               0

Note: By default, pot only counts open PRs.

Authored

Number of PRs authored by the user

Reviewing

Number of PRs currently reviewing, meaning that said user has not approved, or rejected the PR. If user is a requested reviewer, or if user has placed comments but has not approved or rejeted the PR, they are considered active reviewers, and said PR counts as one they are currently reviewing.

Actionable PRs

A PR is considered actionable for a user, when said user can perform any action in said PR, and is probably blocking another user. For example, if john is the author of a PR, and jane places some comments, that PR becomes actionable for john, and non actionable for jane. When john responds to jane's comments and re-requests review from her, PR becomes non actionable for john and actionable for jane.

Untouched PRs

When a user is requested to review a PR, and until the moment they place their first comment, that PR is considered untouched for said user. This is useful when workload ends up unevenly distributed amongst devs, and a dev who has an easier time, tries to decide whose PR they are going to review to even the load.

Details about a specific user's PRs

The above example only shows the accumulated counts for each user. Usually, one will want more details about a specific user's PRs. In that case the --user=<user> option can be used.

$ pot --user=doe

User                  | Authored | Reviewing | Actionable PRs | Untouched PRs
-----------------------------------------------------------------------------
doe                            2           3                3               1

Authored:
---------
Actionable | PR
Yes          Add feature cool (PR_url)
No           Fix bug wah(PR_url)

Reviewing:
----------
Actionable | Untouched | Author: Actionables | PR
Yes          Yes         john: 1               Add feature wow (PR_url)
Yes          No          john: 1               Fix bug dang (PR_url)
No           No          jane: 2               Improve styles (PR_url)

Note: Both --users=<user, names> and --user='user' can be used:

$ pot --users=john,jane --user=doe

And both the accumulative and the specif output will be shown

In the above example, the accumulative data is shown for user doe, as well as some details about each of the PRs they are involved in. This can be used by doe to figure out which PR needs their attention first, or by another user who happened to have some idle time and wants to help out.

List all of user's PR urls

This is used to conveniently open all of a users PRs in the browser

$ pot --user=doe --url-only

This way one can open all of doe's PRs in a browser like this:

$ pot --user=doe | xargs -L1 xdg-open

Configuration

$ pot --config

Follow the wizard to define the github url, repository and owner names.

Note: If pot is used without a configuration, you will be prompted for one.

Contributing

Create an issue describing the purpose of the pull request unless there is one already
Fork the repository ( https://github.com/ioanniswd/pot/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

License

This tool is open source under the MIT License terms.

[Back To Top]

iridakos/pot

pot