==============================
Git Flow Instructions
==============================

This document outlines a **feature-based Git workflow** using the following branch strategy:

- **master**: Always working code that is reviewed, tested and released
- **develop**: Integration branch for all completed features
- **feature**: Short-lived branches for deving specific features

Branch Overview
===============

- **master**:  
  Contains stable releases. Code in this brach should work as described.

- **develop**:  
  The main integration branch where all feature branches are merged after review and testing.

- **<feature_name>**:  
  Branches created off `dev` to implement new features or improvements.

Visual Git Tree
===============

A simplified ASCII diagram to illustrate the flow:

.. code-block:: text

       o---o---o---o---o               (master)
                 \
                  o---o---o---o        (dev)
                     \     \
                      \     o---o      (cool_newer_feature)
                       \
                        o---o          (cool_new_feature)
                  
Workflow
========

Creating a Feature Branch
-------------------------

1. Make sure your local `dev` branch is up to date:

   .. code-block:: bash

       git checkout dev
       git pull origin dev

2. Create a new feature branch:

   .. code-block:: bash

       git checkout -b <feature_name>

3. Work on your feature. Commit regularly:

   .. code-block:: bash

       git add .
       git commit -m "Short description of changes made."

Rebasing onto dev (optional but recommended)
------------------------------------------------

.. note::
    More info on the this topic can `here`_.

.. _here: https://gitolite.com/git-pull--rebase.html

To keep your feature branch up to date with `dev`.

1. Checkout and rebase with the `dev` branch: 

    .. code-block:: bash

        git checkout <feature_name>
        git fetch origin
        git rebase origin/dev

Merging Feature into dev
----------------------------

Once your feature is complete and tested:

1. Push the feature branch to the remote:

    .. code-block:: bash

        git push

    .. note::
        if the branch does not yet exist on the remote use the *--set-upstream* or *-u* flag:
        
        .. code-block:: bash 
        
            git push -u origin <feature_name>

2. Go to github.com and navigate to the remote tho which you pushed the feature branch
 
3. Select the `dev` branch and click on Compare & pull request

    .. image:: ./img/pr_1.PNG

4. Review and finalize PR, when done click on Create pull request

    .. note::
        Pull Request details are T.B.D.

    .. image:: ./img/pr_2.PNG

5. (Optional) Delete the local and remote feature branch:

    .. code-block:: bash

        git branch -d <feature_name>
        git push origin --delete <feature_name>

Releasing to Master
-------------------
T.B.D.

Notes
=====

- Always keep your `dev` and `master` branches clean.
- Feature branches should only live as long as the feature is under development.
- Use descriptive names for feature branches, e.g. `vision_data_pipeline`.