.. _gitworkflow:

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 <https://www.atlassian.com/git/tutorials/comparing-workflows/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``:

   .. code-block:: sh

         git checkout develop
         git checkout -b develop/feature_name

2. Develop the feature and commit changes.

3. Merge the feature branch back into ``develop``:

   .. code-block:: sh

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

4. Delete the feature branch:

   .. code-block:: sh

         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``:

   .. code-block:: sh

         git checkout develop
         git checkout -b fix/bug_description

2. Apply the fix and commit changes.

3. Merge the fix branch back into ``develop``:

   .. code-block:: sh

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

4. Delete the fix branch:

   .. code-block:: sh

         git branch -d fix/bug_description

For current maintenance release (target: ``release``):

1. Create a bug fix branch from ``release``:

   .. code-block:: sh

         git checkout release
         git checkout -b fix/bug_description

2. Apply the fix and commit changes.

3. Merge the fix branch back into ``release``:

   .. code-block:: sh

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

4. Delete the fix branch:

   .. code-block:: sh

         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.

      .. code-block:: sh

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

      .. code-block:: sh

            # 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):

   .. code-block:: sh

         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``):

   .. code-block:: sh

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

4. Cherry-pick the fix into ``develop``:

   .. code-block:: sh

         git checkout develop
         git cherry-pick <commit_hash>

5. Delete the hotfix branch:

   .. code-block:: sh

         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``:

   .. code-block:: sh

         git checkout master
         git merge --no-ff release

3. Tag the release on ``master``:

   .. code-block:: sh

         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``:

   .. code-block:: sh

         git checkout master
         git merge --no-ff develop

2. Tag the release on ``master``:

   .. code-block:: sh

         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):

   .. code-block:: sh

         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:

   .. code-block:: sh

         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:

  .. code-block:: sh

        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.