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 person) and it is ok to consider GitHub as a “synced folder”, then the simplest workflow is not using any branch but just push every change to the main branch. This workflow is the simplest and doesn’t require much knowledge of Git or GitHub. For a team more than 2 people, although you can still use other features of the GitHub, it is generally not a recommended option because it can easily create conflicts.

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.
  3. During a work session, keep committing & pushing to the open PR until ready or until wrapping up the work session.
  4. Get it reviewed (reviews can happen multiple times during (3)).
  5. Branch merged & deleted from GitHub (this can be done automatically—there is an option in repo settings).
  6. Delete 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 effort.
For those who haven’t been using GitHub, it is not immediately clear that one can keep committing to an open PR but it is a nice way to keep others aware of the ongoing work.

Reviews are very good for catching errors and for the spillover of expertise in the team. Yet, it is also a big commitment for the reviewers and often challenging to institute a system. While it is important to encourage reviews, it is probably not a good idea 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), deleting the branch everytime seems to be cleanest option, especially for the Git beginners. Given that requiring more advanced Git knowledge is an extra overhead to the team, this may be a reasonable workflow.