Pull request workflow

[saffaffi]

Here's a description of a relatively "standard" workflow for making changes in a GitHub repo through pull requests when you have push access to the main repo and aren't expected to work through forks. I've broken it down into stages.

Starting out

• It will help avoid headaches for you if you make sure that you're starting from the most up-to-date version of the main branch as possible:

  git checkout main
  git fetch --prune
  git pull

• Create a branch, where you will work on the changes, and switch to it:

  git checkout -b cool-new-thing

  • Some repos/organisations have existing conventions for how to name branches. If there isn't one, then depending on the circumstances you might consider including (1) your initials/username, and/or (2) the issue number. Some examples:
    • gt/cool-new-thing
    • 69-cool-new-thing
    • gt/69-cool-new-thing

• Push the branch to the remote, associating the new remote branch as the upstream of your current branch:

  git push -u origin cool-new-thing

Creating the PR

You won't be able to create a PR until the branch's contents differ from main, so before this step, you should commit and push something.

If the repository has draft PRs enabled (not possible for private repos on a free account, I believe), then it can be a nice idea to create the PR as early as possible in draft mode so that others can keep up to date with how the work is progressing. Otherwise, wait until the work is ready to be reviewed.

• Go to the pull requests tab in the repo's webpage
• Click "New Pull Request"
• The base branch should automatically be set to main. Set the "compare" branch, which is the branch with the changes you want to merge into the base branch, to cool-new-thing.
• Click "Create Pull Request"
• Set a title for the PR (something descriptive, which will probably be similar to the issue title if your work is being driven by an issue)
• Write a short description for the PR and include a phrase like "closes Add aarch64-linux to Nix supported systems list #69", which GitHub will pick up on and use to automatically close the issue if the pull request is merged
• Add labels. For this repo, most of the labels are only useful for issues, not PRs, but you should add a T (type) label. Again, this should correspond to the base issue's type if there is one; in most cases, which type you should use will probably be obvious anyway.
• Click "Create Pull Request"
  • This is the point at which, if you wanted to create a draft PR, you would click the dropdown next to "Create Pull Request" and choose "Create Draft Pull Request" instead

Maintaining the PR

If a PR has been out for a long time and other people are working on the repo, your branch will start to become out of date. It's best to keep an eye on this and try to stay on top of it. There are two main ways to keep your branch up to date:

This is a lot of text about something that will probably never happen in this repo

• Rebase it on main:

  git checkout main
  git pull
  git checkout cool-new-thing
  git rebase main

  • Pros:
    • This will give your branch the cleanest history
    • You will be able to resolve any conflicts in the (imo) most logical way: each of your commits will be re-applied (often called "replayed" by git people) on top of the latest version of main, and at any point if any of the changes in one of your commits tries to modify some code that is different on main than to when you originally made the change, a conflict will occur.
    • If the repository/organisation has a convention or hard requirement that branches must maintain linear history, this is how you do it (rebasing will avoid introducing any merge commits into your branch)
  • Cons:
    • If anyone else has a local copy of your branch, or if they have a PR/branch based on top of your branch rather than main, this is liable to annoy them, especially if you don't warn them first

• Merge main into it:

  git checkout main
  git pull
  git checkout cool-new-thing
  git merge main

  • Pros:
    • This may be less likely to create conflicts.
    • Doesn't annoy anyone who has a branch based on yours as much as rebasing does.
  • Cons:
    • Conflicts are inevitable even if they're less likely with this method, and the way you have to resolve them might feel less logical: now, if any changes on main tried to modify code that is different on your branch now than to the way it was when that change was made, a conflict will arise.
    • Your branch will end up with merge commits in its history.

Getting it merged

• When the changes on the branch are ready to be merged, the first thing to do is to mark the PR as "ready to review" if it was in draft mode before.
• Request review from someone
  • Organisational conventions determine how many people you should ask for review from, and what mix of responses you need to wait for before merging something
• Once it's been approved by enough people, and none of them have requested changes, click merge!
• If changes have been requested, once you've made those changes or argued that you shouldn't, re-request review from the person who requested the changes and wait for them to approve the PR again. Then merge it!