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

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

• 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.

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

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

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

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, 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.
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

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 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.

    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

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

    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