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 #42 is what we'll work with.
1. The first step in allowing Waffle to automatically track your work is to create a branch that contains the issue number:
2. And push it to your remote:
3. When the branch is pushed remotely, Waffle automatically moves the card to "In Progress" and assigns me as an owner.
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 #42". 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 description.
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.
You can hover next to the Pull Request icon below the Waffle card and an arrow will pop up (this only applies for single repo boards). If you click the arrow it will show the Pull Request detail. You can click the Pull Request icon and it will take you to the view in GitHub.
For multi repo boards, you can click the empty space next to the PR icon to see the PR details.
**Important Note: If you use GitHub's issue closing keywords, we will automatically move the card into your New Collaborator PRs 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 Work Started 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 New Collaborator PRs 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.
6. The final step is to review and merge the pull request. Head back to GitHub and merge the pull request.
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).