Branching strategy

[rozyczko]

---
config:
  logLevel: 'debug'
  theme: 'base'
  themeVariables:
    git0: '#a4c8ff'   # master
    git1: '#ff857c'   # hotfix
    git2: '#adc7aa'   # develop
    git3: '#ffb466'   # feature/F1
    git4: '#ed9f70'   # feature/F2
    git5: '#ffde7c'   # feature/F3
    commitLabelColor: '#000'
    commitLabelBackground: '#ccc'
  gitGraph:
    diagramPadding: 40
    showBranches: true
    showCommitLabel: true
    mainBranchName: 'master'
---

gitGraph
  commit id: "Initial commit"

  %% Develop
  branch develop order: 2
  checkout develop
  commit id: "Develop: initial commit"

  %% Feature F1
  branch "feature/F1" order: 3
  checkout "feature/F1"
  commit id: "F1: commit 1"
  commit id: "F1: commit 2"
  checkout develop
  merge "feature/F1" id: "F1: PR (squash)"

  %% Feature F2a
  branch "feature/F2" order: 4

  %% Feature F3a
  branch "feature/F3" order: 5
  checkout "feature/F3"
  commit id: "F3: commit 1"

  %% Feature F2b
  checkout "feature/F2"
  commit id: "F2: commit 1"
  commit id: "F2: commit 2"
  checkout develop
  merge "feature/F2" id: "F2: PR (squash)"

  %% Feature F3b
  checkout "feature/F3"
  merge develop id: "F3: sync from develop"
  commit id: "F3: commit 2"
  checkout develop
  merge "feature/F3" id: "F3: PR (squash)"

  %% Release 1.0.0
  checkout master
  merge develop id: "Release 1.0.0: PR (merge)" tag: "v1.0.0"

  %% Backmerge after 1.0.0
  checkout develop
  merge master id: "Backmerge after v1.0.0"

  %% Hotfix
  checkout master
  branch hotfix order: 1
  checkout hotfix
  commit id: "Hotfix: commit 1"

  %% Release 1.0.1
  checkout master
  merge hotfix id: "Release 1.0.1: PR (merge)" tag: "v1.0.1"

  %% Backmerge after 1.0.1
  checkout develop
  merge master id: "Backmerge after v1.0.1"

Loading

Branch Roles

master — Production branch

• Always represents stable, released code
• Releases are created from this branch and tagged (e.g. v1.0.0)
• Receives changes only via pull requests; creation is automated via the release workflow defined in the templates
• Preserves full merge history (merge commits only)
• Backmerged into develop after publishing a tagged release via the automated backmerge workflow defined in the templates
• Protected branch with enforced rules defined in the templates

develop — Main integration branch

• Used for merging feature branches
• Acts as staging before a release
• Must remain clean and linear
• Must depend only on released (tagged) versions of modules from master
• Receives changes only via pull requests
• Squash and merge only
• Protected branch with enforced rules defined in the templates

feature/* — Short-lived development branches

• Created from develop
• Used for new functionality or improvements
• May temporarily depend on development branches of other modules
• Must depend only on released (tagged) versions from master before merging
• Merged into develop via squash merge
• Must be deleted after merging

hotfix/* — Emergency fix branches

• Created from master
• Used for critical production fixes
• Merged directly into master via pull request
• Tagged as a new patch release (e.g. v1.0.1)
• Automatically backmerged into develop
• Must be deleted after merging

gh-pages — Documentation branch

• Reserved for generated documentation
• Updated automatically by CI
• No manual changes allowed
• Protected branch with enforced rules defined in the templates

Merge Strategy

• feature/* → develop → Squash merge
• develop → master → Merge commit
• hotfix/* → master → Merge commit
• master → develop → Automated backmerge

---

Links to the original discussions: #4, #28
Default branch naming (master vs main): #6
Fixed diagram and branch protection: #45