Recommended Workflow Using Pull Requests & Automatic Work Tracking

kellihsf edited this page Dec 9, 2015 · 20 revisions

Below is the recommended workflow for utilizing Waffle's automatic work tracking capabilities. Current automatic work tracking features include:

  • move Issues into In Progress by adding issue number in the branch name
  • customize which column pull requests go for both collaborator and non-collaborator issued PR's
  • visually "connect" issues to pull requests without using the closing/fixes/resolves keywords
  • automatic movement of closed issues to the Done column

I've created a new issue on one of my test boards. For the purposes of this walkthrough, card #21 is what we'll work with.
screen shot 2015-12-09 at 2 22 41 pm

  1. The first step in allowing Waffle to automatically track your work is to create a branch that contains the issue number...

    screen shot 2015-12-09 at 4 38 49 pm

  2. and push it to your remote.
    screen shot 2015-12-09 at 4 39 08 pm

  3. When the branch is pushed remotely, Waffle automatically moves the card to "In Progress" and assigns me as an owner. screen shot 2015-12-09 at 2 25 28 pm

  4. After you're done with the work, head over to GitHub and issue a pull request back to your main branch. Note that in the title of the pull request, I've put the standard GitHub text "closes #21". This lets GitHub know that the pull request should close your issue when it is successfully merged. You can also reference issues across different repos for the same effect like "closes owner/repo#123". Waffle will recognize issue references you put in either the PR title or the PR body. screen shot 2015-12-09 at 2 45 58 pm

  5. Once the pull request is created, the card is moved into "Needs Review" (this is a part of our dev process) and the pull request is attached to the issue card. By default, all boards are configured to have collaborator-issued pull requests go to "In Progress." It is possible to configure to which column the card / pull request is moved by following this FAQ. screen shot 2015-12-09 at 2 46 55 pm

Important Note: If you use GitHub's issue closing keywords, we will automatically move the card into your Collaborator PR start column (for our team, this is configured to "Needs Review.") If you don't want to use the closing keywords but would still like your PR and Issue connected, you can use Waffle's Connect Keywords prior to the issue number and we will move the referenced issue to your In Progress Start column. For both cases, we will also assign the referenced issue to the pull request creator.

Example: If you opened pull request #24 for your repository and titled it "Closes #21, Connected to #23," you would see issue #21 move to your Collaborator PR Start column, and it would reference PR #24. Issue #23 would move to your In Progress column (if it wasn't there already) and would also reference PR #24.

screen shot 2015-12-09 at 3 31 32 pm

  1. You can hover on the "Pull Request" bar below the Waffle card and an arrow will pop up. If you click the arrow it will show the Pull Request detail. If you click the Pull Request icon, it will take you to the view in GitHub.
    screen shot 2015-12-09 at 3 32 52 pm

  2. The final step is to review and merge the pull request. Head back to GitHub and merge the pull request... screen shot 2015-12-09 at 3 37 22 pm

  3. And once that's done, the card is automatically moved to "Done", and the pull request is marked as gray since it is merged (closed pull requests will show up in gray as well). screen shot 2015-12-09 at 3 51 47 pm