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 | Workflow Example: Ideal Workflow

  • Feature branches should ALWAYS be based on either the main branch or another feature branch.

• Propagating Changes

  More Info | Workflow Example: 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.

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

Loading

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

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

Loading

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

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

    SCOTCH --> main

Loading

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
8. The day after a release, main is back ported to scotch-env.

    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

Loading

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.

    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

Loading

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.

    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

Loading