-
Notifications
You must be signed in to change notification settings - Fork 4.9k
Collaborator PR Guide
This guide is for collaborators. It describes the Pull Requests merging procedure using Magit, Forge and Waffle.io.
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.
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
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.
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.