# Proposed Netchex Branching Strategy

> Note: This page is still a work in progress and may contain incomplete or inaccurate data.

## Introduction

### Definitions

* **"Feature Branch"** -- Any branch used to track distinct work related to a particular Azure DevOps ticket that has been reviewed by the team. This might include `bug.123.release`, `story.123.release`, or `task.123.release` branches.

* **"Merging"** -- All references to merging X branch into Y branch refers to creating a Pull Request in Azure DevOps.

### What is each branch for?

* `scotch-env` -- This is the team development environment. Manual QA testing is done in this environment.

* `staging.candidate` -- Staging branch where all tickets going to prod that have passed QA live. Automated and Manual Regression is done on this branch

* `release.candidate` -- Release branch where all tickets that passed regression live. This branch will be merged with `main` during the releases

* `main` -- Production

### Strategy / Rule Set

* #### Creating Branches

   [More Info](#creating-branches-1) | [Workflow Example: Ideal Workflow](#ideal-workflow)
  
   - Feature branches should **ALWAYS** be based on either the `main` branch or another feature branch.

* #### Propagating Changes

   [More Info](#propagating-changes-1) | [Workflow Example: Ideal Workflow](#ideal-workflow)

  - The `scotch-env` branch should only ever have feature branches merged into it.
  - The `staging.candidate` branch should only ever have feature branches merged into it.
  - The `release.candidate` branch should only ever have the `staging.candidate` branch merged into it
  - The `main` branch should only ever have the  `release.candidate` branch merged into it.

## Strategy

### Creating Branches

New feature branches should always be based on either the `main` branch or another feature branch. This is to ensure that the branch can distinctly be merged into the `scotch-env` and `release.candidate` branches without any need for cherry picking.

::: mermaid
graph LR
    subgraph "Core"
      scotch-env(fa:fa-code-branch scotch-env)
      main(fa:fa-code-branch main)
      staging.candidate(fa:fa-code-branch staging.candidate)
    end

    subgraph "Feature"
      TASK[fa:fa-code-branch task.1]
      TASK2[fa:fa-code-branch task.2]
      TASK3[fa:fa-code-branch task.3]
    end

    main -.- TASK -.- TASK3
    main -.- TASK2
:::

### Propagating Changes

When propagating the changes made in a feature branch, the branch should be merged separately to both the `scotch-env` branch and the `release.candidate` branch. 

- If the intention is to deploy it to `scotch-env` for basic testing, the feature branch can be merged / deployed to the `scotch-env` branch at any time.
- When features in `scotch-env` passes QA, they can be merged into `staging.candidate`
- When all features in `staging.candidate` pass regression, the branch can be merged into `release.candidate`

::: mermaid
graph LR
    subgraph "Feature"
      FEAT[fa:fa-code-branch story.123]
    end

    subgraph "Core"
      SCOTCH(fa:fa-code-branch scotch-env)
      STAGING(fa:fa-code-branch staging.candidate)
      RELEASE(fa:fa-code-branch release.candidate)
      main(fa:fa-code-branch main)
    end

    FEAT --> SCOTCH & STAGING
    STAGING --> RELEASE --> main
:::

### Post Release Maintenance

After a release, the `scotch-env` will need to be re-synced with the `main` branch. We can do this by back porting `main` into `scotch-env` after each release with a pull request

::: mermaid
graph LR
    SCOTCH(fa:fa-code-branch scotch-env)
    main(fa:fa-code-branch main)

    SCOTCH --> main
:::

## Workflow Examples
### Ideal Workflow

In this example: 

1. `task.123` is created from the `main` branch. 
2. `task.123` has changes added to it.
3. PR is made for `task.123` into `scotch-env` for team to code review.
4. `task.123` is merged to `scotch-env` for dev and manual qa testing.
5. Once `task.123` has passed manual QA testing, PR is made for `task.123` into `staging.candidate`.
6. Once regression passes on `staging.candidate` the branch is merged to `release.candidate`.
    - *Note: This step is not performed by the engineer*
7. `release.candidate` is merged into `main` during the release process.
    - *Note: This step is not performed by the engineer*
6. The day after a release, `main` is back ported to `scotch-env`.

::: mermaid
    gitGraph
      commit id:"..."
      branch release.candidate
      branch staging.candidate
      branch scotch-env

      checkout main
      commit id:" "
      
      checkout main
      branch task.123
      commit id:"commit 1"
      commit id:"commit 2"

      checkout scotch-env
      merge task.123
      commit id:"QA Passes" type: HIGHLIGHT

      checkout staging.candidate
      merge task.123

      commit id:"Regression Passes" type: HIGHLIGHT

      checkout release.candidate
      merge staging.candidate

      commit id:"Release to Prod" type: HIGHLIGHT

      checkout main
      merge release.candidate
      commit id:"Backport"

      checkout scotch-env
      merge main
:::

### Revert Change Workflow

In this example:

1. `task.123` is created from the `main` branch. 
2. `task.123` has changes added to it.
3. PR is made for `task.123` into `scotch-env` for team to code review.
4. `task.123` is merged to `scotch-env` for dev and manual qa testing.
5. `task.123` fails QA.
6. `task.123` is reverted from `scotch-env` via the PR made in step 4.
7. The fix is implemented in the `task.123` branch.
8. PR is made for `task.123` into `scotch-env` for team to code review the fix.
9. Once `task.123` has passed manual QA testing, PR is made for `task.123` into `staging.candidate`.
10. Once regression passes on `staging.candidate` the branch is merged to `release.candidate`.
    - *Note: This step is not performed by the engineer*
11. `release.candidate` is merged into `main` during the release process.
    - *Note: This step is not performed by the engineer*
12. The day after a release, `main` is back ported to `scotch-env`.


::: mermaid
    gitGraph
      commit id:"..."
      branch release.candidate
      branch staging.candidate
      branch scotch-env

      checkout main
      commit id:" "
      
      checkout main
      branch task.123

      commit id:"commit 1"
      commit id:"commit 2"

      checkout scotch-env
      merge task.123

      commit id:"Revert task.123 fails QA" type: REVERSE

      checkout task.123
      commit id:"Patch QA Issue"

      checkout scotch-env
      merge task.123
      commit id:"QA Passes" type: HIGHLIGHT

      checkout staging.candidate
      merge task.123

      commit id:"Regression Passes" type: HIGHLIGHT

      checkout release.candidate
      merge staging.candidate

      commit id:"Release to Prod" type: HIGHLIGHT

      checkout main
      merge release.candidate
      commit id:"Backport"

      checkout scotch-env
      merge main
:::

### Feature Branch Workflow
This workflow will cover how to handle stories that rely on each other.

In this example we have task 1 and task 2. Lets say task 1 is to create a new settings page and task 2 is to add a form to that new settings page.

1. `task.1` is created from the `main` branch.
2. `task.1` has changes added to it
3. PR is made for `task.1` into `scotch-env` for team to code review
4. `task.1` is merged to `scotch-env` for dev and manual qa testing.
5. Once `task.1` has passed manual QA testing, PR is made for `task.1` into `staging.candidate`.
6. `task.2` is made off of the `task.1` branch
7. `task.2` has changes added to it
8. PR is made for `task.2` into `scotch-env` for team to code review
9. `task.2` is merged to `scotch-env` for dev and manual qa testing.
10. Once `task.2` has passed manual QA testing, PR is made for `task.2` into `staging.candidate`.
11. Once regression passes on `staging.candidate` the branch is merged to `release.candidate`.
    - *Note: This step is not performed by the engineer*
12. `release.candidate` is merged into `main` during the release process.
    - *Note: This step is not performed by the engineer*
13. The day after a release, `main` is back ported to `scotch-env`.


::: mermaid
    gitGraph
      commit id:"..."
      branch release.candidate
      branch staging.candidate
      branch scotch-env

      checkout main
      commit id:" "
      
      checkout main
      branch task.1

      commit id:"commit 1.1"
      commit id:"commit 1.2"

      checkout scotch-env
      merge task.1
      commit id:"Task 1 Passes QA" type: HIGHLIGHT

      checkout staging.candidate
      merge task.1

      checkout task.1
      branch task.2

      commit id:"commit 2.1"
      commit id:"commit 2.2"

      checkout scotch-env
      merge task.2
      commit id:"Task 2 Passes QA" type: HIGHLIGHT

      checkout staging.candidate
      merge task.2

      commit id:"Regression Passes" type: HIGHLIGHT

      checkout release.candidate
      merge staging.candidate

      commit id:"Release to Prod" type: HIGHLIGHT

      checkout main
      merge release.candidate
      commit id:"Backport"

      checkout scotch-env
      merge main
:::