Git Workflow

This document describes the Git workflow used in the guidata project, based on a master branch, a develop branch, and feature-specific branches. It also defines how bug fixes are managed.

Note

This workflow is a simplified version of the Gitflow Workflow. It has been adapted to suit the needs of the guidata project at the current stage of development.

Branching Model

Main Branches

  • master: Represents the stable, production-ready version of the project.

  • develop: Used for ongoing development and integration of new features.

Feature Branches

  • feature/feature_name: Used for the development of new features.

    • Created from develop.

    • Merged back into develop once completed.

    • Deleted after merging.

Release Branch

  • release: Represents the current maintenance line for patch releases.

    • Created from master after a stable release when the first patch is needed.

    • Accepts fix/xxx and hotfix/xxx branch merges.

    • Merged back into master for each patch release tag (e.g., 3.7.1, 3.7.2).

    • Reset or recreated when starting a new minor/major release cycle.

Note

The release branch is not versioned (no release/3.7.x). It always represents “the current maintenance line.” When a new minor version is released (e.g., 3.8.0), the old release branch is deleted and a new one is created from the fresh tag when the first patch for 3.8.1 is needed.

Bug Fix Branches

  • fix/xxx: Used for general bug fixes that are not urgent.

    • Created from develop (for next feature release) or release (for patch release).

    • Merged back into the originating branch once completed.

    • Deleted after merging.

  • hotfix/xxx: Used for urgent production-critical fixes.

    • Created from release (if exists) or master (if no release branch yet).

    • Merged back into release or master.

    • The fix is then cherry-picked into develop.

    • Deleted after merging.

Note

Hotfixes (high-priority fixes) will be integrated in the next maintenance release (X.Y.Z -> Z+1), while fixes (low-priority fixes) will be integrated in the next feature release (X.Y -> Y+1).

Documentation Branches

When working on documentation that is not related to source code (e.g. training materials, user guides), branches should be named using the doc/ prefix.

Examples:

  • doc/training-materials

  • doc/user-guide

This naming convention improves clarity by clearly separating documentation efforts from code-related development (features, fixes, etc.).

Workflow for New Features

  1. Create a new feature branch from develop:

    git checkout develop
git checkout -b develop/feature_name

  2. Develop the feature and commit changes.

  3. Merge the feature branch back into develop:

    git checkout develop
git merge --no-ff develop/feature_name

  4. Delete the feature branch:

    git branch -d develop/feature_name

Warning

Do not leave feature branches unmerged for too long. Regularly rebase them on develop to minimize conflicts.

Workflow for Regular Bug Fixes

For next feature release (target: develop):

  1. Create a bug fix branch from develop:

    git checkout develop
git checkout -b fix/bug_description

  2. Apply the fix and commit changes.

  3. Merge the fix branch back into develop:

    git checkout develop
git merge --no-ff fix/bug_description

  4. Delete the fix branch:

    git branch -d fix/bug_description

For current maintenance release (target: release):

  1. Create a bug fix branch from release:

    git checkout release
git checkout -b fix/bug_description

  2. Apply the fix and commit changes.

  3. Merge the fix branch back into release:

    git checkout release
git merge --no-ff fix/bug_description

  4. Delete the fix branch:

    git branch -d fix/bug_description

Warning

Do not create a fix/xxx branch from a develop/feature_name branch. Always branch from develop or release to ensure fixes are correctly propagated.

# Incorrect:
git checkout develop/feature_name
git checkout -b fix/wrong_branch

# Correct:
git checkout develop
git checkout -b fix/correct_branch

Workflow for Critical Hotfixes

  1. Create a hotfix branch from release (or master if no release branch exists):

    git checkout release  # or: git checkout master
git checkout -b hotfix/critical_bug

  2. Apply the fix and commit changes.

  3. Merge the fix back into release (or master):

    git checkout release  # or: git checkout master
git merge --no-ff hotfix/critical_bug

  4. Cherry-pick the fix into develop:

    git checkout develop
git cherry-pick <commit_hash>

  5. Delete the hotfix branch:

    git branch -d hotfix/critical_bug

Warning

Do not merge fix/xxx or hotfix/xxx directly into master without following the workflow. Ensure hotfixes are cherry-picked into develop to avoid losing fixes in future releases.

Workflow for Patch Releases

When ready to release a patch version (e.g., 3.7.1, 3.7.2):

  1. Ensure the release branch contains all desired fixes.

  2. Merge release into master:

    git checkout master
git merge --no-ff release

  3. Tag the release on master:

    git tag -a v3.7.1 -m "Release version 3.7.1"
git push origin master --tags

  4. Keep the release branch for additional patches in the same minor version series.

Workflow for Minor/Major Releases

When ready to release a new minor or major version (e.g., 3.8.0, 4.0.0):

  1. Merge develop into master:

    git checkout master
git merge --no-ff develop

  2. Tag the release on master:

    git tag -a v3.8.0 -m "Release version 3.8.0"
git push origin master --tags

  3. Delete the old release branch (if exists):

    git branch -d release
git push origin --delete release

  4. Create a new release branch from master when the first patch for 3.8.1 is needed:

    git checkout master
git checkout -b release
git push -u origin release

Best Practices

  • Regularly rebase feature branches on develop to stay up to date:

    git checkout develop/feature_name
git rebase develop

  • Avoid long-lived branches to minimize merge conflicts.

  • Ensure bug fixes in release or master are always cherry-picked to develop.

  • Clearly differentiate between fix/xxx (non-urgent fixes) and hotfix/xxx (critical production fixes).

  • When creating the release branch, update CHANGELOG to indicate which version it targets (e.g., add a comment in the merge commit: “Create release branch for v3.7.x maintenance”).

  • The release branch always represents the current maintenance line. To know which version it targets, check the most recent tag on master or the CHANGELOG.

Takeaway

This workflow ensures a structured yet flexible development process while keeping master stable and develop always updated with the latest changes.

The release branch provides a dedicated maintenance line for patch releases, allowing develop to proceed with new features without interference. This solves the problem of coordinating unreleased changes across the PlotPyStack ecosystem (DataLab, Sigima, PlotPy, guidata, PythonQwt) by providing a stable branch for CI testing during maintenance cycles.