Pull Request Workflow - acquaman/acquaman GitHub Wiki

The following page details the life-cycle of a GitHub pull request and how it ideally moves through the Boards provided by ZenHub. In general, a pull request will start in New Issues and will always move to right along the board until it finally ends in Closed. The path a pull request should take is New Issues, To Do, In Progress, Closed. There are a couple of exceptions. One is where a pull request is created before it is ready to be reviewed. In this case, the pull request lives in the Not Ready For Review pipeline and should have the Work In Progress label. The other is if a pull request gets stalled by lack of final testing due to changes made from comments in the code review. In this case, the pull request is moved to the Testing pipeline and should have the Awaiting Testing. All the pipelines will be outlined on their intended function and how issues move in and out below.

New Issues

Function: Holds all pull requests that have been newly created.

Pull requests only enter this pipeline when they are newly created.
Pull requests can be moved out of the pipeline in the following ways:

  1. Moved to To Do because the code needs to be reviewed. A reviewer and a best guess estimate should be assigned.
  2. If the code is not ready for review yet, it can be moved into the Not Ready For Review pipeline and given the label Work In Progress.

Not Ready For Review

Function: This is a placeholder pipeline for pull requests that have been created but are not ready for a code review. This is typically used when developers want feedback on their code because they are unsure of their solution or want a sanity check before continuing to the rest of the task. They should have the Work In Progress label.

To Do

Function: Holds all pull requests that should be reviewed. They should have an estimate assigned to them by the creator of the pull request, have a reviewer assigned to it, and have the Ready For Review label.

Pull requests can enter this pipeline when the developer is ready for a code review.
Pull requests leave this pipeline when the assigned reviewer does the code review.

In Progress

Function: Holds pull requests while it is being reviewed and if changes are being made due to comments made by the reviewer. Unlike issues, there may be many pull requests in the pipeline since reviewing tasks is not nearly as onerous of a task as writing the code.

Pull requests enter the pipeline once the reviewer begins reviewing the code.
Pull requests can leave the pipeline in one of three ways:

  1. The review is successfully completed. In this case the code is merged because it has passed its code review.
  2. If changes were required and more testing is required, but the equipment is unavailable for an extended period of time, then the pull request will be moved to the Testing pipeline.
  3. If during the process of the code review the code should be abandoned, then it will be closed and have the Project Tracking Disabled label added to it.

Testing

Function: Holds all pull requests that have been stalled due to lack of access to available testing.

Pull requests enter the pipeline once it has been established that an extended period of time is required before testing can be completed on the code changes introduced from the code review.
Pull requests can leave the pipeline in one of two ways:

  1. The tests are successful and the code is merged.
  2. If the it turns out that the code needs to be abandoned then, then it will be clsed and have the Project Tracking Disabled label added to it.

Closed

Function: Holds all completed pull requests. Pull requests that move here will be retrospected to close the loop on whether the code review went as expected. The estimate will become higher if it turns out that a lot of back and forth and code changes were required. Assuming the pull request has been completed via normal means it should contain the following pieces of information:

  • Complexity estimate.
  • A time estimate on how long it took to review the pull request AND a time estimate for any extra work that was required due to comments made during the review process in the style of Time Estimate: X minutes/hours/days. These will be in separate comments as the person who makes the comments will likely not be making the changes themselves.
  • An actual complexity to close the loop on the review.

Pull requests can enter this pipeline any time they are closed. If the issue is closed by not following any of the processes outlined above, then the label Project Tracking Disabled must be added.