Tip of the Week: Branch, Review, and Learn

Dave Bunten (@d33bs) Research Data Engineer

February 13, 2023 November 25, 2024

Tip of the Week: Branch, Review, and Learn

Git provides a feature called branching which facilitates parallel and segmented programming work through commits with version control. Using branching enables both work concurrency (multiple people working on the same repository at the same time) as well as a chance to isolate and review specific programming tasks. This article covers some conceptual best practices with branching, reviewing, and merging code using Github.

Please note: the content below represents one opinion in a larger space of Git workflow concepts (it’s not perfect!). Developer cultures may vary on these topics; be sure to acknowledge people and culture over exclusive or absolute dedication to what is found below.

TLDR (too long, didn’t read); Use git branching techniques to segment the completion of programming tasks, gradually and consistently committing small changes (practicing festina lente or “make haste, slowly”). When a group of small changes are ready from branches, request pull request reviews and take advantage of comments to continuously improve the work. Prepare for a branch merge after review by deciding which merge strategy is appropriate and automating merge requirements with branch protection rules.

Concept: Coursework Branching

flowchart LR
 subgraph Course
    direction LR
    open["open\nassignment"]
    turn_in["review\nassignment"]
  end
  subgraph Student ["     Student"]
    direction LR
    work["completed\nassignment"]
  end
  open -.-> turn_in
  open --> |works towards| work
  work --> |seeks review| turn\_in

An example course and student assignment workflow.

Git branching practices may be understood in context with similar workflows from real life. Consider a student taking a course, where an assignment is given to them to complete. In addition to the steps shown in the diagram above, it’s important to think about why this pattern is beneficial:

• Completing an assignment allows us as social, inter-dependent beings to present new findings which enable learning and amalgamation of additional ideas from others.
• The timebound nature of assignments enables us to practice some form of timeboxing so as to minimize tasks which may take too much time.
• Segmenting applied learning in distinct, goal-orientated chunks helps make larger topics easier to understand.

Branching to Complete an “Assignment”

%%{init: { 'logLevel': 'debug', 'theme': 'default' , 'themeVariables': {
      'git0': '#4F46E5',
      'git1': '#10B981',
      'gitBranchLabel1': '#ffffff'
} } }%%
    gitGraph
       commit id: "..."
       commit id: "opened"
       branch assignment
       checkout assignment
       commit id: "completed"
       checkout main

An example git diagram showing assignment branch based off main.

Following the course assignment workflow, the diagram above shows an in-progress assignment branch based off of the main branch. When the assignment branch is created, we bring into it everything we know from main (the course) so far in the form of commits, or groups of changes to various files. Branching allows us to make consistent and well described changes based on what’s already happened without impacting others work in the meantime.

Branching best practices:

• Keep the name and work with branches dedicated to a specific and focused purpose. For example: a branch named fix-links-in-docs might entail work related to fixing HTTP links within documentation.
• Consider the use of Github Forks (along with branches within the fork) to help further isolate and enrich work potential. Forks also allow remixing existing work into new possibilities.
• festina lente or “make haste, slowly”: Commits on any branch represent small chunks of a cohesive idea which will eventually be brought to main. It is often beneficial to be consistent with small, gradual commits to avoid a rushed or incomplete submission. The same applies more generally for software; taking time upfront to do things well can mean time saved later.

Reviewing the Branched Work

%%{init: { 'logLevel': 'debug', 'theme': 'default' , 'themeVariables': {
      'git0': '#6366F1',
      'git1': '#10B981',
      'gitBranchLabel1': '#ffffff'
} } }%%
    gitGraph
       commit id: "..."
       commit id: "opened"
       branch assignment
       checkout assignment
       commit id: "completed"
       checkout main
       merge assignment id: "reviewed"

An example git diagram showing assignment branch being merged with main after a review.

The diagram above depicts a merge from the assignment branch to pull the changes into the main branch, simulating an assignment being returned for review within a course. While merges may be forced without review, it’s a best practice create a Pull Request (PR) Review (also known as a Merge Request (MR) on some systems) and then ask other members of your team to review it. Doing this provides a chance to make revisions before code changes are “finalized” within the main branch.

Github provides special tools for reviews which can assist both the author and reviewer:

• Keep code changes intended for review small, enabling reviewers to reason through the work to more quickly provide feedback and practicing incremental continuous improvement (it may be difficult to address everything at once!). This also may denote the git history for a repository in a clearer way.
• Github comments: Overall review comments (encompassing all work from the branch) and Inline comments (inquiring about individual lines of code) may be provided. Inline comments may also include code suggestions, which allows for code-based revision suggestions that may be committed directly to the branch using markdown codeblocks ( ``suggestion `).
• Github issues: Creating issues from comments allows the creation of new repository issues to address topics outside of the current PR.

Merging the Branch after Review

%%{init: { 'logLevel': 'debug', 'theme': 'default' , 'themeVariables': {
      'git0': '#6366F1'
} } }%%
    gitGraph
       commit id: "..."
       commit id: "opened"
       commit type: HIGHLIGHT id: "reviewed"
       commit id: "...."

An example git diagram showing the main branch after the assignment branch has been merged (and removed).

Changes may be made within the assignment branch until the work is in a state where the authors and reviewers are satisfied. At this point, the branch changes may be merged into main. Approvals are sometimes provided informally (for ex., with a comment: “LGTM (looks good to me)!”) or explicitly (for ex., approvals within Github) to indicate or enable branch merge readiness . After the merge, changes may continue to be made in a similar way (perhaps accounting for concurrently branched work elsewhere). Generally, a merged branch may be removed afterwards to help maintain an organized working environment (see Github PR branch removal).

Github provides special tools for merging:

• Decide which merge strategy is appropriate (there are many!): There are many merge strategies within Github (merge commits, squash merges, and rebase merging). Take time to understand them and choose which one works best.
• Consider using branch protection to automate merge requirements: The main or other branches may be “protected” against merges using branch protection rules. These rules can require reviewer approvals or automatic status checks to pass before changes may be merged.
• Use merge queuing to manage multiple PR’s: When there are many unmerged PR’s, it can sometimes be difficult to document and ensure each are merged in a desired sequence. Consider using merge queues to help with this process.

Additional Resources

The links below may provide additional guidance on using these git features, including in-depth coverage of various features and related configuration.

• Software Carpentry: Version Control with Git
• Github: Git Guide
• Atlassian: What is version control?
• Git Lab: Git