GitHub Workflow

Git, GitHub

The optimal workflow depends on many factors, such as the size of the team, the nature & composition of the team, the complexity of the project, the toolchain used by the team, etc. Therefore, it is important to pick a workflow that suits the team & project the best. It is probably good to start with a simple workflow.

Academic research projects

Push to the main branch

If the team is very small (e.g., one or two people) and it is ok to consider GitHub as a “synced folder”, then the simplest workflow is not using any branch but just pushing every change to the main branch. This workflow is the simplest and doesn’t require much knowledge of Git or GitHub. For a team of more than 2 people, although you can still use other features of GitHub, it is generally not a recommended option because it can easily create conflicts.

To avoid conflicts, try to be agile—don’t keep your unpushed changes for long. Keep the GitHub and local clone as synchronized as possible.

  1. Start a work session with pulling all changes
  2. Make commits small.
  3. Push & pull often.

A small team with short-lived branches

Consider each branch & pull request as a work session. For everyone in the team, do:

  1. Create a local branch for a work session.
  2. Push the branch & make a pull request (with a clear title about the work session) that outlines the changes. Note that the actual work for the PR has not been done yet. In the PR content, feel free to create to-do items and ask not to merge until they are all checked off.
  3. During a work session, keep committing & pushing to the open PR (yes you can do that) until ready or until wrapping up the work session.
  4. Add (request) reviewers and get it reviewed if possible/necessary. Reviews can happen multiple times during (3) and this is often better because reviewers would only need to look at a small amount of changes. If code review creates too much friction, consider merging quickly (even without review) after a short wait period.
  5. Merge the branch. Then delete the branch from GitHub (this can be done automatically—there is an option in repository setting).
  6. Delete the work branch locally.
  7. Pull the main branch and go back to (1).

The reason for (2-3) is to keep the team aware of what everyone is on, which helps avoid conflicts or duplicated efforts.

Regarding (4), reviews are very good for catching errors and the spillover of expertise in the team. Yet, it is also a big commitment for the reviewers and often challenging to institute. While it is important to encourage reviews, it is probably not a good idea for a small team to make a strict policy about reviews, which can significantly slow down the progress and introduce too much friction. If it is difficult to get a review in time, it is probably better to move on with no review or a much more simplistic review.

Regarding (5-7), although deleting the branch every time may not always be the most efficient or “right” options, but I find it the cleanest and easy-to-understand workflow, especially for the Git beginners. If you don’t delete the local branch, it will require rebasing or merging later and that can easily lead to the git hell™.

Given that requiring more advanced Git knowledge is a substantial extra overhead to the team, I recommend this as a reasonably simple and frictionless workflow that works for most teams.

A larger team with strict code review (open source model)

If the stake of the software is high and/or the team is large, the team may institute a more strict process that resemble common open-source workflows. In this workflow, there will be likely a set of core developers who are in charge of reviewing and merging new code. They will be the gatekeepers. Contributers will be asked to create clean, self-contained pull requests—rather than a ‘work session’—which will then be reviewed and merged by the core developers.