Skip to content

Instantly share code, notes, and snippets.

@jacobdrury

jacobdrury/01_branching_strategy.md

Last active February 16, 2023 22:55
Show Gist options
  • Save jacobdrury/e4bc69d534e5a84e618d0f304e9f12d8 to your computer and use it in GitHub Desktop.
Save jacobdrury/e4bc69d534e5a84e618d0f304e9f12d8 to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. jacobdrury revised this gist Feb 16, 2023. 2 changed files with 0 additions and 0 deletions.
    0 branching_strategy.md → 01_branching_strategy.md
    View file
    File renamed without changes.
    0 azure_devops_translation.md → 02_azure_devops_translation.md
    View file
    File renamed without changes.
  2. jacobdrury revised this gist Feb 16, 2023. 2 changed files with 298 additions and 10 deletions.
    291 changes: 291 additions & 0 deletions azure_devops_translation.md
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,291 @@
    # 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
    :::
    17 changes: 7 additions & 10 deletions branching_strategy.md
    View file
    Original file line number Diff line number Diff line change
    @@ -37,14 +37,6 @@
    - 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.

    <!-- * #### Reverting Changes
    [Workflow Example: Reverting Changes](#revert-change-workflow)
    - When reverting changes, it's important that they are reverted from both the `dev` branch as well as the `qa` branch.
    - If the changes have not yet been staged for deploy on the `qa` branch, there is no need to revert them on that branch.
    - Revert commits should be made directly on the affected branch, be that `qa` or `dev`. If we need to revert a change that has been applied to the `main` branch, we should create the revert commit in the `qa` and `dev` branches and open a PR to merge the `qa` branch into the `main` branch. -->

    ## Strategy

    ### Creating Branches
    @@ -94,7 +86,7 @@ graph LR
    STAGING --> RELEASE --> main
    ```

    #### Post Release Maintenance
    ### 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

    @@ -107,7 +99,6 @@ graph LR
    ```

    ## Workflow Examples

    ### Ideal Workflow

    In this example:
    @@ -118,7 +109,9 @@ In this example:
    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
    @@ -172,7 +165,9 @@ In this example:
    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`.


    @@ -238,7 +233,9 @@ In this example we have task 1 and task 2. Lets say task 1 is to create a new se
    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`.


  3. jacobdrury revised this gist Feb 16, 2023. 1 changed file with 12 additions and 2 deletions.
    14 changes: 12 additions & 2 deletions branching_strategy.md
    View file
    Original file line number Diff line number Diff line change
    @@ -6,9 +6,19 @@

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

  4. jacobdrury revised this gist Feb 16, 2023. 1 changed file with 37 additions and 40 deletions.
    77 changes: 37 additions & 40 deletions branching_strategy.md
    View file
    Original file line number Diff line number Diff line change
    @@ -106,7 +106,7 @@ In this example:
    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 the feature has passed manual QA testing, PR is made for `task.123` into `staging.candidate`.
    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`.
    7. `release.candidate` is merged into `main` during the release process.
    6. The day after a release, `main` is back ported to `scotch-env`.
    @@ -160,7 +160,7 @@ In this example:
    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 the feature has passed manual QA testing, PR is made for `task.123` into `staging.candidate`.
    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`.
    11. `release.candidate` is merged into `main` during the release process.
    12. The day after a release, `main` is back ported to `scotch-env`.
    @@ -215,73 +215,70 @@ In this example:
    ### Feature Branch Workflow
    This workflow will cover how to handle stories that rely on each other.

    In this example we have story ticket 1 and story ticket 2. Ticket 1 is to create a new settings page. Ticket 2 is to add a form to that new settings page.
    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. `story.1.release` is created from the `main` branch.
    2. `story.1.dev` is created from `story.1.release`
    3. `story.1.dev` has changes added to it
    4. `story.1.dev` is merged to `story.1.release` via a PR
    3. `story.1.release` is merged to `scotch-env` for dev and qa testing via a PR
    5. Once story 1 has passed regression it is then merged into `release.candidate` by the QA team
    6. `story.2.release` is created from the `story.1.release` branch
    7. `story.2.dev` is created from the `story.2.release` branch
    8. `story.2.dev` has changes added to it.
    9. `story.2.dev` is merged into `story.2.release` via a PR
    10. `story.2.release` is deployed to `scotch-env` via a PR
    11. Once the story 2 has passed regression it is then merged into `release.candidate` by the QA team
    12. Later on, once the feature is released to production, `main` is back ported to `scotch-env` via a PR to
    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`.
    12. `release.candidate` is merged into `main` during the release process.
    13. The day after a release, `main` is back ported to `scotch-env`.


    ```mermaid
    gitGraph
    commit id:"..."
    branch release.candidate
    branch scotch
    branch staging.candidate
    branch scotch-env
    checkout main
    commit id:" "
    checkout main
    branch story.1.release
    branch task.1
    checkout story.1.release
    branch story.1.dev
    checkout story.1.dev
    commit id:"commit 1.1"
    commit id:"commit 1.2"
    checkout story.1.release
    merge story.1.dev
    checkout scotch
    merge story.1.release
    commit id:"Regression 1 Passes" type: HIGHLIGHT
    checkout scotch-env
    merge task.1
    commit id:"Task 1 Passes QA" type: HIGHLIGHT
    checkout release.candidate
    merge story.1.release
    checkout staging.candidate
    merge task.1
    checkout story.1.release
    branch story.2.release
    branch story.2.dev
    checkout task.1
    branch task.2
    commit id:"commit 2.1"
    commit id:"commit 2.2"
    checkout story.2.release
    merge story.2.dev
    checkout scotch-env
    merge task.2
    commit id:"Task 2 Passes QA" type: HIGHLIGHT
    checkout scotch
    merge story.2.release
    commit id:"Regression 2 Passes" type: HIGHLIGHT
    checkout staging.candidate
    merge task.2
    commit id:"Regression Passes" type: HIGHLIGHT
    checkout release.candidate
    merge story.2.release
    merge staging.candidate
    commit id:"Release to Prod" type: HIGHLIGHT
    checkout main
    merge release.candidate
    commit id:"Backport"
    checkout scotch
    checkout scotch-env
    merge main
    ```
  5. jacobdrury revised this gist Feb 16, 2023. 1 changed file with 36 additions and 38 deletions.
    74 changes: 36 additions & 38 deletions branching_strategy.md
    View file
    Original file line number Diff line number Diff line change
    @@ -103,13 +103,13 @@ graph LR
    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 the feature has passed manual QA testing, `task.123` is merged into `staging.candidate`
    6. Once regression passes on `staging.candidate` the branch is merged to `release.candidate`
    7. `release.candidate` is merged into `main` during the release process
    6. The day after a release, `main` is back ported to `scotch-env`
    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 the feature 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`.
    7. `release.candidate` is merged into `main` during the release process.
    6. The day after a release, `main` is back ported to `scotch-env`.

    ```mermaid
    gitGraph
    @@ -152,65 +152,63 @@ In this example:

    In this example:

    1. The `story.123.release` branch is created from the `main` branch.
    2. The `story.123.dev` branch is created from the `story.123.release` branch.
    3. Changes are added to the `story.123.dev` branch.
    4. `story.123.dev` is merged to `story.123.release` via a PR
    5. The `story.123.release` branch is deployed to the `scotch-env` environment via a PR.
    6. QA Regression fails when testing the changes
    7. The `story.123.release` changes are reverted from the `scotch-env` branch.
    8. The fix is implemented in the `story.123.dev` branch.
    9. `story.123.dev` is merged into `story.123.release` via a PR
    10. `story.123.release` is deployed to `scotch-env` via a PR
    11. `story.123.release` passes regression and is merged into `release.candidate`
    12. Later on, once the feature is released to production, `main` is back ported to `scotch-env` via a PR to
    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 the feature 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`.
    11. `release.candidate` is merged into `main` during the release process.
    12. The day after a release, `main` is back ported to `scotch-env`.


    ```mermaid
    gitGraph
    commit id:"..."
    branch release.candidate
    branch scotch
    branch staging.candidate
    branch scotch-env
    checkout main
    commit id:" "
    checkout main
    branch story.123.release
    checkout story.123.release
    branch story.123.dev
    branch task.123
    checkout story.123.dev
    commit id:"commit 1"
    commit id:"commit 2"
    checkout story.123.release
    merge story.123.dev
    checkout scotch
    merge story.123.release
    checkout scotch-env
    merge task.123
    commit id:"Revert (scotch) story.123.release" type: REVERSE
    commit id:"Revert task.123 fails QA" type: REVERSE
    checkout story.123.dev
    checkout task.123
    commit id:"Patch QA Issue"
    checkout story.123.release
    merge story.123.dev
    checkout scotch-env
    merge task.123
    commit id:"QA Passes" type: HIGHLIGHT
    checkout staging.candidate
    merge task.123
    checkout scotch
    merge story.123.release
    commit id:"Regression Passes" type: HIGHLIGHT
    checkout release.candidate
    merge story.123.release
    merge staging.candidate
    commit id:"Release to Prod" type: HIGHLIGHT
    checkout main
    merge release.candidate
    commit id:"Backport"
    checkout scotch
    checkout scotch-env
    merge main
    ```

  6. jacobdrury revised this gist Feb 16, 2023. 1 changed file with 50 additions and 52 deletions.
    102 changes: 50 additions & 52 deletions branching_strategy.md
    View file
    Original file line number Diff line number Diff line change
    @@ -6,11 +6,11 @@

    ### Definitions

    **" Release 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.
    **"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.

    **" Dev Feature Branch"** -- Any branch used to track dev work related to a particular Azure DevOps ticket. This might include `bug.123.dev`, `story.123.dev`, or `task.123.dev` branches.
    **"Merging"** -- All references to merging X branch into Y branch refers to creating a Pull Request in Azure DevOps.

    ### Strategy Rule Set
    ### Strategy / Rule Set

    * #### Creating Branches

    @@ -22,9 +22,10 @@

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

    - The `release.candidate` branch should only ever have release feature branches merged into it.
    - The `scotch-env` branch should only ever have release feature branches merged into it.
    - The `main` branch should only ever have the `release.candidate` branch merged into it.
    - 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.

    <!-- * #### Reverting Changes
    @@ -44,46 +45,43 @@ New feature branches should always be based on either the `main` branch or anoth
    graph LR
    subgraph "Core"
    scotch-env(fa:fa-code-branch scotch-env)
    MAIN(fa:fa-code-branch main)
    release.candidate(fa:fa-code-branch release.candidate)
    main(fa:fa-code-branch main)
    staging.candidate(fa:fa-code-branch staging.candidate)
    end
    subgraph "Feature"
    FEAT.RELEASE[fa:fa-code-branch story.123.release]
    FEAT.DEV[fa:fa-code-branch story.123.dev]
    BUG.RELEASE[fa:fa-code-branch bug.123.release]
    BUG.DEV[fa:fa-code-branch bug.123.dev]
    TASK.RELEASE[fa:fa-code-branch task.123.release]
    TASK.DEV[fa:fa-code-branch task.123.dev]
    TASK[fa:fa-code-branch task.1]
    TASK2[fa:fa-code-branch task.2]
    TASK3[fa:fa-code-branch task.3]
    end
    MAIN -.- FEAT.RELEASE -.- FEAT.DEV
    MAIN -.- BUG.RELEASE -.- BUG.DEV
    MAIN -.- TASK.RELEASE -.- TASK.DEV
    main -.- TASK -.- TASK3
    main -.- TASK2
    ```

    ### Propagating Changes

    When propagating the changes made in a feature branch, the release feature 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 release feature branch can be merged / deployed to the `scotch-env` branch at any time.
    - When `scotch-env` passes regression, all release feature branches can be merged into `release.candidate`
    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 "Core"
    SCOTCH(fa:fa-code-branch scotch-env)
    MAIN(fa:fa-code-branch main)
    QA(fa:fa-code-branch release.candidate)
    subgraph "Feature"
    FEAT[fa:fa-code-branch story.123]
    end
    subgraph "Feature"
    FEAT[fa:fa-code-branch story.123.release]
    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 & QA
    QA --> MAIN
    FEAT --> SCOTCH & STAGING
    STAGING --> RELEASE --> main
    ```

    #### Post Release Maintenance
    @@ -93,9 +91,9 @@ After a release, the `scotch-env` will need to be re-synced with the `main` bran
    ```mermaid
    graph LR
    SCOTCH(fa:fa-code-branch scotch-env)
    MAIN(fa:fa-code-branch main)
    main(fa:fa-code-branch main)
    SCOTCH --> MAIN
    SCOTCH --> main
    ```

    ## Workflow Examples
    @@ -104,49 +102,49 @@ graph LR

    In this example:

    1. `story.123.release` is created from the `main` branch.
    2. `story.123.dev` is created from `story.123.release`
    3. `story.123.dev` has changes added to it
    4. `story.123.dev` is merged to `story.123.release` via a PR
    3. `story.123.release` is merged to `scotch-env` for dev and qa testing via a PR
    5. Once the feature has passed regression it is then merged into `release.candidate` by the QA team
    6. Later on, once the feature is released to production, `main` is back ported to `scotch-env` via a PR to

    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 the feature has passed manual QA testing, `task.123` is merged into `staging.candidate`
    6. Once regression passes on `staging.candidate` the branch is merged to `release.candidate`
    7. `release.candidate` is merged into `main` during the release process
    6. The day after a release, `main` is back ported to `scotch-env`

    ```mermaid
    gitGraph
    commit id:"..."
    branch release.candidate
    branch scotch
    branch staging.candidate
    branch scotch-env
    checkout main
    commit id:" "
    checkout main
    branch story.123.release
    checkout story.123.release
    branch story.123.dev
    checkout story.123.dev
    branch task.123
    commit id:"commit 1"
    commit id:"commit 2"
    checkout story.123.release
    merge story.123.dev
    checkout scotch-env
    merge task.123
    commit id:"QA Passes" type: HIGHLIGHT
    checkout staging.candidate
    merge task.123
    checkout scotch
    merge story.123.release
    commit id:"Regression Passes" type: HIGHLIGHT
    checkout release.candidate
    merge story.123.release
    merge staging.candidate
    commit id:"Release to Prod" type: HIGHLIGHT
    checkout main
    merge release.candidate
    commit id:"Backport"
    checkout scotch
    checkout scotch-env
    merge main
    ```

  7. jacobdrury created this gist Jan 24, 2023.
    291 changes: 291 additions & 0 deletions branching_strategy.md
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,291 @@
    # Proposed Netchex Branching Strategy

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

    ### Definitions

    **" Release 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.

    **" Dev Feature Branch"** -- Any branch used to track dev work related to a particular Azure DevOps ticket. This might include `bug.123.dev`, `story.123.dev`, or `task.123.dev` branches.

    ### 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 `release.candidate` branch should only ever have release feature branches merged into it.
    - The `scotch-env` branch should only ever have release feature branches merged into it.
    - The `main` branch should only ever have the `release.candidate` branch merged into it.

    <!-- * #### Reverting Changes
    [Workflow Example: Reverting Changes](#revert-change-workflow)
    - When reverting changes, it's important that they are reverted from both the `dev` branch as well as the `qa` branch.
    - If the changes have not yet been staged for deploy on the `qa` branch, there is no need to revert them on that branch.
    - Revert commits should be made directly on the affected branch, be that `qa` or `dev`. If we need to revert a change that has been applied to the `main` branch, we should create the revert commit in the `qa` and `dev` branches and open a PR to merge the `qa` branch into the `main` branch. -->

    ## 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)
    release.candidate(fa:fa-code-branch release.candidate)
    end
    subgraph "Feature"
    FEAT.RELEASE[fa:fa-code-branch story.123.release]
    FEAT.DEV[fa:fa-code-branch story.123.dev]
    BUG.RELEASE[fa:fa-code-branch bug.123.release]
    BUG.DEV[fa:fa-code-branch bug.123.dev]
    TASK.RELEASE[fa:fa-code-branch task.123.release]
    TASK.DEV[fa:fa-code-branch task.123.dev]
    end
    MAIN -.- FEAT.RELEASE -.- FEAT.DEV
    MAIN -.- BUG.RELEASE -.- BUG.DEV
    MAIN -.- TASK.RELEASE -.- TASK.DEV
    ```

    ### Propagating Changes

    When propagating the changes made in a feature branch, the release feature 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 release feature branch can be merged / deployed to the `scotch-env` branch at any time.
    - When `scotch-env` passes regression, all release feature branches can be merged into `release.candidate`


    ```mermaid
    graph LR
    subgraph "Core"
    SCOTCH(fa:fa-code-branch scotch-env)
    MAIN(fa:fa-code-branch main)
    QA(fa:fa-code-branch release.candidate)
    end
    subgraph "Feature"
    FEAT[fa:fa-code-branch story.123.release]
    end
    FEAT --> SCOTCH & QA
    QA --> 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. `story.123.release` is created from the `main` branch.
    2. `story.123.dev` is created from `story.123.release`
    3. `story.123.dev` has changes added to it
    4. `story.123.dev` is merged to `story.123.release` via a PR
    3. `story.123.release` is merged to `scotch-env` for dev and qa testing via a PR
    5. Once the feature has passed regression it is then merged into `release.candidate` by the QA team
    6. Later on, once the feature is released to production, `main` is back ported to `scotch-env` via a PR to


    ```mermaid
    gitGraph
    commit id:"..."
    branch release.candidate
    branch scotch
    checkout main
    commit id:" "
    checkout main
    branch story.123.release
    checkout story.123.release
    branch story.123.dev
    checkout story.123.dev
    commit id:"commit 1"
    commit id:"commit 2"
    checkout story.123.release
    merge story.123.dev
    checkout scotch
    merge story.123.release
    commit id:"Regression Passes" type: HIGHLIGHT
    checkout release.candidate
    merge story.123.release
    checkout main
    merge release.candidate
    commit id:"Backport"
    checkout scotch
    merge main
    ```

    ### Revert Change Workflow

    In this example:

    1. The `story.123.release` branch is created from the `main` branch.
    2. The `story.123.dev` branch is created from the `story.123.release` branch.
    3. Changes are added to the `story.123.dev` branch.
    4. `story.123.dev` is merged to `story.123.release` via a PR
    5. The `story.123.release` branch is deployed to the `scotch-env` environment via a PR.
    6. QA Regression fails when testing the changes
    7. The `story.123.release` changes are reverted from the `scotch-env` branch.
    8. The fix is implemented in the `story.123.dev` branch.
    9. `story.123.dev` is merged into `story.123.release` via a PR
    10. `story.123.release` is deployed to `scotch-env` via a PR
    11. `story.123.release` passes regression and is merged into `release.candidate`
    12. Later on, once the feature is released to production, `main` is back ported to `scotch-env` via a PR to


    ```mermaid
    gitGraph
    commit id:"..."
    branch release.candidate
    branch scotch
    checkout main
    commit id:" "
    checkout main
    branch story.123.release
    checkout story.123.release
    branch story.123.dev
    checkout story.123.dev
    commit id:"commit 1"
    commit id:"commit 2"
    checkout story.123.release
    merge story.123.dev
    checkout scotch
    merge story.123.release
    commit id:"Revert (scotch) story.123.release" type: REVERSE
    checkout story.123.dev
    commit id:"Patch QA Issue"
    checkout story.123.release
    merge story.123.dev
    checkout scotch
    merge story.123.release
    commit id:"Regression Passes" type: HIGHLIGHT
    checkout release.candidate
    merge story.123.release
    checkout main
    merge release.candidate
    commit id:"Backport"
    checkout scotch
    merge main
    ```

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

    In this example we have story ticket 1 and story ticket 2. Ticket 1 is to create a new settings page. Ticket 2 is to add a form to that new settings page.

    1. `story.1.release` is created from the `main` branch.
    2. `story.1.dev` is created from `story.1.release`
    3. `story.1.dev` has changes added to it
    4. `story.1.dev` is merged to `story.1.release` via a PR
    3. `story.1.release` is merged to `scotch-env` for dev and qa testing via a PR
    5. Once story 1 has passed regression it is then merged into `release.candidate` by the QA team
    6. `story.2.release` is created from the `story.1.release` branch
    7. `story.2.dev` is created from the `story.2.release` branch
    8. `story.2.dev` has changes added to it.
    9. `story.2.dev` is merged into `story.2.release` via a PR
    10. `story.2.release` is deployed to `scotch-env` via a PR
    11. Once the story 2 has passed regression it is then merged into `release.candidate` by the QA team
    12. Later on, once the feature is released to production, `main` is back ported to `scotch-env` via a PR to


    ```mermaid
    gitGraph
    commit id:"..."
    branch release.candidate
    branch scotch
    checkout main
    commit id:" "
    checkout main
    branch story.1.release
    checkout story.1.release
    branch story.1.dev
    checkout story.1.dev
    commit id:"commit 1.1"
    commit id:"commit 1.2"
    checkout story.1.release
    merge story.1.dev
    checkout scotch
    merge story.1.release
    commit id:"Regression 1 Passes" type: HIGHLIGHT
    checkout release.candidate
    merge story.1.release
    checkout story.1.release
    branch story.2.release
    branch story.2.dev
    commit id:"commit 2.1"
    commit id:"commit 2.2"
    checkout story.2.release
    merge story.2.dev
    checkout scotch
    merge story.2.release
    commit id:"Regression 2 Passes" type: HIGHLIGHT
    checkout release.candidate
    merge story.2.release
    checkout main
    merge release.candidate
    commit id:"Backport"
    checkout scotch
    merge main
    ```