# GitFlow Guide
GitFlow is a way of structuring pull requests and branches, that intends to simplify the branching workflow in a larger project.

## The main branches
- **`master`**
- Where tags are pushed (release tags)
- represents the stable environment
- sometimes named `main`
- **`develop`**
- Where new additions and non-urgent fixes are added
- sometimes named `dev`

## Supporting branches
> Unlike the main branches, these branches always have a limited life time, since they will be removed eventually.

### Branches based from develop
- **`feature/[name]`**
- Branches with this prefix contains features
- merged to develop
- Ex: `feature/control-localization`
- **`bugfix/[name]`**
- Branches with this prefix contains unreleased bug fixes
- merge to develop
- Ex: `bugfix/required-validation-not-working`
- **`release/[name]`**
- Branches with this prefix are created to prepare an upcoming release
- merge to develop and master
- you should perform version bumbing if required
- the name must be the new version number
- the version should be minor or major update for features and patch for bugfixes
- Ex: current version 1.0.0 > major update > `release/2.0.0`
- Ex: current version 1.0.0 > minor update > `release/1.1.0`
- Ex: current version 1.0.0 > patch update > `release/1.0.1`

### Branches based from master
- **`hotfix/[name]`**
- Branches with this prefix are urgent to get to the stable environment to fix bugs
- merge to develop and master
- Considered as a patch version
- name could be patch version
- Ex: current version 1.2.3 > `hotfix/1.2.4`

# Semantic Versioning
Given a version number MAJOR.MINOR.PATCH, increment the:
1. MAJOR version when you make incompatible API changes,
2. MINOR version when you add functionality in a backwards compatible manner, and
3. PATCH version when you make backwards compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the `MAJOR.MINOR.PATCH` format.

You can't skip versions
- 1.0.0 > 1.0.1 ✔ - patch update
- 1.0.0 > 1.1.0 ✔ - minor update
- 1.0.0 > 2.0.0 ✔ - major update
- 1.0.0 > 1.0.2 ❌ - skip patch
- 1.0.0 > 1.2.0 ❌ - skip minor
- 1.0.0 > 3.0.0 ❌ - skip major
- 1.0.0 > 1.1.1 ❌ - skip patch 1.1.0
- 1.0.0 > 2.0.1 ❌ - skip pathc 2.0.0
- 1.0.0 > 2.1.0 ❌ - skip minor 2.0.0

---

# GitFlow in action

## Init new git repo

git init -b main    # init git with default branch called main
git checkout -b dev # create dev branch

## Init in existing repo
1. Make sure to complete any old branches and clean the repo
2. Remove all branches except `main`
3. Create `dev` branch from main
4. Add latest version number as a tag on the main (Ex: 3.0.2)

## Create new feature
1. Create new branch `feature/[name]` from dev
2. Complete all changes (as much commits as you want)
3. Merge to dev (local merge or using a pull request)
4. Delete `feature/[name]` branch

## Create new bugfix
1. Create new branch `bugfix/[name]` from dev
2. Complete all changes (as much commits as you want)
3. Merge to dev (local merge or using a pull request)
4. Delete `bugfix/[name]` branch

## Create new release
1. After making some changes to dev `feature` or `bugfix`
2. Create new branch `release/[version]` from dev
3. Bump version number if needed and commit
4. Merge to main (local merge or using a pull request)
5. Merge to dev (local merge or using a pull request)
6. Add a tag with release version to main
7. Delete `release/[version]` branch

## Create new hotfix
1. Create new branch `hotfix/[version]` from main
2. Complete all changes (as much commits as you want)
3. Merge to main (local merge or using a pull request)
4. Merge to dev (local merge or using a pull request)
5. Add a tag with patch version to main
6. Delete `hotfix/[version]` branch

## References
- https://nvie.com/posts/a-successful-git-branching-model/
- https://github.com/petervanderdoes/gitflow-avh