Skip to content

Git Workflow

Jump to bottom
Joe McCormick edited this page Aug 22, 2025 · 3 revisions

🐝 Git Workflow

This document is intended for both BeeGFS developers and community contributors who want to understand how changes flow through the BeeGFS codebase.

TL;DR – The default branch (typically main) always tracks active development on the current major release. Release branches are used to backport fixes/changes to a specific minor release.

Overview

This document outlines our Git workflow strategy for managing BeeGFS releases following semantic versioning. It reflects our desire to:

  • Minimize developer friction and overhead.
  • Allow for precise backporting of fixes to patch specific minor releases.
  • Allow scheduled CI workflows to run on the branch where most development occurs.
    • Note GitHub only supports scheduled workflows on the default branch.
  • Support a clear, predictable release lifecycle.

Diagram

Git Flow Diagram

Branch Summary

Branch Purpose
main (default) Active development branch for the next major or minor release.
release-7.4 Release branch where fixes to 7.4 are backported.
release-8.0 Release branch where fixes to 8.0 are backported.
release-8.1 Release branch where fixes to 8.1 are backported.
username/feat/* Feature branches off main
username/fix/* Bug fix branches off main

🔁 Development & Release Workflow

🧪 Major/Minor Releases

Development Phase

  • New features are developed on */feat/* branches and merged into the main branch.
  • Bug fixes, doc updates, and CI changes affecting main are merged into the main branch.
    • If these changes also affect previous releases, they may be backported to the appropriate release branch(es). See Patch Releases below.
    • If these changes only affect previous release(s), corresponding branches should be based on the target release branch and only merged to that release branch. See Patch Releases below.

🧊 Soft Code Freeze

Prior to a planned major/minor release a soft code freeze will be initiated:

  • No new PRs are allowed unless critical. The focus is on reviewing/testing/merging outstanding PRs to the main branch and ensuring it is stable.
  • Depending on the size of the release one or more beta releases may be tagged to allow packages to be built for internal/external testing.

🧱 Hard Code Freeze

After the soft code freeze a hard code freeze is enacted:

  • No additional PRs are merged unless critical. The focus is on testing and updating documentation.
    • While automated checks run on every PR and continuously on the main branch to catch issues early, the intent of the hard code freeze is to validate the release as a whole. All changes for that release are tested together through functional, integration, performance/stress, and interoperability testing to ensure regressions or new issues are caught before shipping.
  • Depending on the size of the release one or more release candidates will be tagged to allow packages to be built for final internal/external testing.

🚀 Release Day

  • A tag for the release is pushed to all repos (e.g., v8.1.0), triggering package builds. A new release branch (e.g., release-8.1) is also created to support future backports.
  • Once packages are available in all repositories, the corresponding tag is provided to our release automation which handles collecting all packages and building them into the OS package repository.
  • The OS package repository is sanity checked then published along with updated user docs.

🔧 Patch Releases

  • Bug fixes merged into main may be backported to one or more release-x branches, as needed, according to the BeeGFS support policy.
  • Some fixes (e.g., for older versions) may only apply to a specific release-x branch and can be made directly there, without involving main.
  • Patch releases are tagged and ship as needed from release-x branches (e.g., v8.0.1).

📌 Summary

  • All active development (features, fixes, docs, CI, etc.) takes place in the main branch.
    • The main branch must remain stable and always ready for the next major or minor release.
    • On release day, a tag (e.g., v8.1.0) is created on main and a corresponding release-X.Y branch is created to support future backports.
  • Critical or supported bug fixes may be backported from main to one or more release-X.Y branches based on the BeeGFS support policy.
    • Some fixes may only apply to older release branches and can be committed directly there.
    • Patch releases are tagged and shipped as needed from the relevant release-X.Y branch (e.g., v8.0.1).

This workflow minimizes overhead, supports a stable release cadence, and simplifies collaboration for both internal and external contributors.

Clone this wiki locally