# 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.