Collaborator PR Guide

This guide is for collaborators. It describes the Pull Requests merging procedure using Magit, Forge and Waffle.io.

Overview

We don't use the GitHub green button to merge or squash a PR. Instead we work with PR offline, editing history and fixing things in new commits. When everything is OK we push to the develop branch all the commits at once.

This strategy allow us to concentrate on the PR content instead of the form, i.e. a PR does not need to be perfect to be merged since we can fix the form offline and push all the commits at once.

But if a PR is indeed perfectly done, then the rebase button is a viable option, although you should reserve this option for very small or trivial changes.

In this document we'll see how to work offline with PR using Magit and its Forge extension.

This approach has a big downside though: several collaborators could work on the same PR at the same time. To fix this we use Waffle.io to flag PRs that are being merged.

Working with PRs using forge

Forge comes with the GitHub layer. Once installed you need to set it up with a GitHub personal access token after which you can do a M-x forge-pull in the Magit status buffer to fetch all the PRs.

Now you can follow this pattern:

• open magit with SPC g s
• checkout a PR with b y and searching it by name or ID
• donate all commits to develop by doing A d and selecting your current branch first and the develop branch second
• switch to the develop branch by pressing b b and selecting it
• delete the PR branch and remote by doing b x and selecting it

Tip: Forge can be a bit slow especially on a project with a lot of issues/PRs like this one, and you might also encounter bugs. To help you in these situations remember you still have the option of downloading patches with wget or curl and applying them with git am. To do this, get the link to the PR from GitHub and append .patch to it:

wget https://github.com/syl20bnr/spacemacs/pull/10684.patch
#                                                   [______]
#                                                      ^
#--------- remember to add the .patch at the end ------|
git am 10684.patch

Using Waffle.io to better collaborate

Waffle.io is a great project management service based on GitHub issue tags. We can use this service to mark the PRs we are currently working on so we don't duplicate our effort.

Step by step guide

Go to Waffle.io Spacemacs project page and log in with your GitHub account. You'll see the Kanban board like this:

First be sure to change the filter to PRs only.

The important columns are Merging... and Merged. Each column is bound to a tag. Moving a card from one column to another updates the tags of the corresponding issue. Cards in Merging... column get the merging... tag and cards in Merged column get the merged tag.

When you are working on a PR in Magit move the corresponding card to the Merging... column and assign the card to you.

When you have finished cherry-picking the PR then move the card to the Merged column. You are not compelled to push the cherry-picked PR directly after moving the card to the Merged column, you can push them later, the important thing is to correctly move the cards to the Merged column to show other collaborators that this PR is merged (it shows also the tag merged for contributors and users).

Finally when you push all the cherry-picked PRs to the develop branch you can use the Merged column to quickly navigate to the issue using the little GitHub button on the card and close it with an explanation of what you did (optional) and the now familiar sentence:

Thank you!
Cherry-picked into develop branch, you can safely delete your branch.

Tip: You can use the save reply feature of GitHub to save this sentence.