Recommended pull request workflow with gh pr query

Introduction

The --todo option in the gh-pr-query tool supports a particular workflow for pull request reviewers and authors. This wiki page documents this suggested workflow.

Workflow for pull request reviewers

Reviewing on GitHub

• Whenever you request a change, do so by starting the request with a Markdown checkbox. You can do this by typing - [ ] at the start of the line or by clicking on the task list icon in GitHub's editing toolbar. GitHub will render this as an unchecked checkbox, and gh-pr-query --todo will interpret it as an outstanding todo item.

  • Example: - [ ] Something I'd like you to do

  • Note the Markdown formatting: in - [ ], there must be a space after the dash, between the open and close brackets, and after the close bracket. Tip: if GitHub doesn't render it as a checkbox, then gh-pr-query --todo won't pick it up either. Edit your comment to fix your Markdown formatting.

• Multiple requests can be made in a single comment, but separate requests should be listed on their own line, each starting with a checkbox.

• Note that only text on the same line as a checkbox will be shown by gh-pr-query --todo, so if you need multiple lines to explain your request, try to put a self-contained summary on the first line. (The output from gh-pr-query --todo will give a link to the full comment, so you can see the full details by clicking that link.)

• If a request is optional (e.g., a nit-pick), you can denote it by starting your text with [optional], (optional) or optional: (case-insensitive). When running gh-pr-query --todo, optional todos will be listed after all non-optional todos. Examples:

  • - [ ] [optional] If it's not too hard, please do X
  • - [ ] (OPTIONAL) It would be helpful if you could do Y
  • - [ ] Optional: If possible, please do Z

Reviewing outstanding todo items

• To review all outstanding todo items in a pull request, run gh-pr-query with the -t or --todo option. This will output a list of all unchecked todo items, sorted by date. This list will also show the author of each todo item and will provide links back to the original comments on GitHub so you can see the context of each request.

• If you would just like to see requests made by a particular user (such as yourself), you can also provide the -u or --filter-username option, giving a GitHub username.

• If an item has been completed, use the link in the output from gh-pr-query --todo to open the relevant comment on GitHub. Then simply click on the relevant checkbox to check it off. It won't appear the next time you run gh-pr-query --todo.

  • GitHub allows you to check off items in comments that you have written. In addition, if you have write permission to the repository, you can check off items in anyone's comments. In general, though, it is best if you allow a comment author to check off their own items.

• If gh-pr-query --todo has no output, or only outputs optional todos, that is an indication that the pull request is ready to be merged.

• If you would like to provide a list of still-outstanding todo items to the pull request author without requiring them to install this tool, you can copy the output from gh-pr-query --todo and paste it into a comment in the relevant pull request. The formatting of the output of this tool is designed so that this will not create duplicate todo items.

Workflow for pull request authors

• You can view a list of requests using gh-pr-query --todo. Each request will contain a link to the original comment, so you can see the context of the request.

• Once you feel you have satisfied a given request, you can leave a comment on GitHub noting that you have done so, if you don't think it will be obvious to the reviewer. In general, the reviewer who made a comment should be the one to check off the relevant checkbox; the pull request author should NOT check off checkboxes themselves.

• If you want to keep track of todos that you have come up with yourself, you can use the same workflow as a pull request reviewer, as described above.