4  Branch Management

In (collaborative) software development, branch management is useful when using versioning control and GitHub. Creating a new branch offers an isolated workspace for any task, whether it’s adding a new feature or addressing a bug, regardless of its scale.

The core advantage of branching is that it provides separate, dedicated environments for code development to both individuals and teams, independent of the main codebase. This approach enables parallel development streams, allowing for experimentation and modification without impacting the stable main version of the project. This approach is also valuable for projects with just one developer!

Adopting a branching strategy is about establishing a set of practices that govern code writing, merging, and release processes within a version control environment. It provides a structured framework, ensuring smooth collaboration and efficient management of the shared codebase.

Consideration

For open source projects, details about the branching strategy, how to collaborate and contribute can be communicated in the repository’s contributing guidelines in the file CONTRIBUTING.md. - eScience Center - Example project contributing guidelines - GitHub - Documentation contribution guidelines

4.1 Branch models

There are various branch management workflows developed, but a recommendation for research software would be to use GitHub Flow or Gitflow.

GitHub Flow is a simplified and straightforward workflow, relying on a single main branch. Developers create feature branches off of the master branch, work on their changes, and then merge them back into the master branch via pull requests. The process is built around the principle of continuous collaboration, and it is particularly useful for projects where regular updates and deployments are common.

Gitflow involves two main branches: main and develop. Developers create feature branches off of the develop branch. Once a feature is complete, it’s merged back into the develop branch.

In short, GitHub Flow is simpler and more suitable for projects that prioritize continuous integration and deployment, while Gitflow offers a more structured approach for managing larger projects with distinct release cycles and versioning requirements. For research software, both approaches can be used, depending on the projects’ needs.

Further reading

4.2 Branch management in action

4.2.1 Personal projects and small teams

GitHub Flow model: - Typically starts with just the main branch. - Use branches for unfinished/untested ideas. - Use branches when you are not sure about a change. - Add tags to mark important milestones.

%%{init: {'theme': 'base', 'gitGraph': {'showCommitLabel': false}}}%%
gitGraph LR:
   commit
   commit
   branch "feature A"
   checkout "feature A"
   commit
   commit type:REVERSE
   checkout main

   commit
   branch "feature B"
   checkout "feature B"
   commit
   commit
   commit

   checkout main
   merge "feature B"
   commit tag:"Paper submission"

When applying this workflow for projects with a few persons, you accept things breaking sometimes.

For projects with a few persons, where more control is required, follow:

  • The main branch is write-protected.
  • You create new feature branches for changes.
  • Changes are reviewed before they are merged to the main branch.
  • Only merges to main branch through pull requests (and optionally code reviews).

GitHub decided to rename the default branch from master to main for new repositories after October 2020. This change was part of a broader industry move to replace terms that may be considered insensitive or non-inclusive. It’s important to note that while the terms main and master refer to the default branch in a repository, they are functionally the same. Be aware that repositories created before October 2020 may still use master instead of main.

4.2.2 Distributing releases

When you need to distribute releases, your main branch will serve as the latest stable version.

  • The main branch is protected and read-only.
  • You set up a develop branch for active development.
  • Create feature branches of the develop branch.
  • Merge feature branches (through Pull Requests) back to develop.
  • Only merge develop into main when releasing a new stable (and tested) version.

%%{init: {'theme': 'base', 'gitGraph': {'showCommitLabel': false}}}%%
gitGraph
    
   commit tag:"v0.1.0"
   branch develop
   commit

   checkout develop
   commit
   commit
   checkout main
   merge develop tag:"v0.2.0"

   checkout develop
   commit
   commit
   checkout main
   merge develop tag:"v0.3.0"

   checkout develop
   commit
   commit

4.2.3 Add additional supporting branches

When a critical bug in a production version must be resolved immediately, a hotfix branch may be branched off from the corresponding tag on the main branch that marks the production version. After fixing, hotfix is then merged with both main and develop.

%%{init: {'theme': 'base', 'gitGraph': {'showCommitLabel': false}}}%%
gitGraph
    
   commit tag:"v0.2.0"
   branch develop
   commit
   commit
   commit
   commit
   checkout main
   branch hotfix
   commit
   commit
   checkout develop
   merge hotfix
   checkout main
   merge hotfix tag:"v0.2.1"
   checkout develop
   commit
   commit
   checkout main
   merge develop tag:"v0.3.0"

Full Gitflow model
Further reading