direct-file/docs/adr/2024-11-21_production-branching-strategy.md

Github Branching Strategy for FS25 Production Development

Status: Accepted
Date: 2024-11-21
Decision: Option 1 - Set `main` as "future features" branch for all TY25+ work and create a long-term `production` TY24 branch and merge from `production` into main

Context and Problem Statement

This ADR documents our short-term Github branching strategy for filing season 2025 (FS25), starting in January 2025.

We don't currently support multiple tax years simultaneously in Direct File and all active tax logic in the repo at any point in time is currently for a single tax year. In the pilot year, filing season 2024 (FS24), we only supported tax year 2023 (TY23) and in the second year starting in January 2025 (FS25), we plan to only support tax year 2024 (TY24). We also have an additional product goal of keeping Direct File open year-round, but only supporting one tax year at a time for now. Supporting multiple tax years concurrently in production is on the roadmap for TY26/FS27.

Our development goals in the second year of Direct File are to simultaneously support two modes of operating within our single Github repository:

1. Support the active tax logic in production for TY24, fix bugs and potentially add small tax scope items that should be deployed to taxpayers in production during FS25
2. Start development on future scope beyond this year - Factgraph and foundational improvements and future TY25 tax logic that should not be deployed to taxpayers in production until after FS25

Decision Drivers

Some factors considered in the decision

• Ease of use for developers: how can we make it easy for developers to use the right branch by default? A majority of the team will focus on active production TY25 tax scope and a minority will be working on future scope
• Complexity for devops: understand the workload and changes required for devsecops with each strategy
• Error workflow: if a PR is merged to the wrong branch, how easy is the workflow for fixing the error?
• Minimize git history issues: consider alternatives to the cherry-picking approach we took last year in order to make production git history cleaner and more accurate. Avoid situations where cherry-picked commits do not include important prerequisite changes.

Considered Options

Option 1: Set main as "future features" branch for all TY25+ work and create a long-term production TY24 branch and merge from production into main

Branches

• main: The evergreen branch consisting of both future features and production TY24 code. This branch is not to be deployed to taxpayers in production during FS25
• production: The long-running branch consisting of only production TY24 code, to be deployed to taxpayers in production during FS25 on a weekly basis via release branches.
• Pre-commit hooks and branch protection rules will also need to be configured on this new branch enforcing code review, CI tests, scans and more

Releases and Deployment

• Cut releases from production
• Deploy from production
• Reserve the TEST environment for regular deployments from main for testing future features
• Continue to use the PRE-PROD environment for production branch testing
• Continue these two branches throughout the year
• When it is time to cutover to TY25 (December 2025 or January 2026), fork a new production branch from main and continue the same processes for the next tax year (or move to Option 3 or another long-term branching strategy)

Developer workflows

The first step is to identify whether the work is destined for the current production branch, or whether it is work that is only for future tax years.

For production TY24

1. Check out and pull production branch
   • git checkout production
   • git pull
2. Create/check out new branch for feature/fix work
   • git checkout -b branch-for-ticket
3. Create a PR for changes into production branch
4. Squash and merge PR into production branch
5. Create a second PR from the production branch into main and resolve conflicts if needed. We are unable to automate this step at this time, but would like to merge into main on every PR in order to make the conflict resolution easier.
   • Note: Regular merge (not "Squash and Merge") is recommended here

For future features

1. Check out main branch
2. Make PR against main branch
3. Merge into main branch

Error workflow

If a change intended for production is accidentally made on main

1. Revert PR from main
2. Make new PR against production and follow developer workflow for production TY24 above

If a change intended for main is accidentally made on production

1. Notify release manager in the event the change might be destined for deployment and coordinate as needed
2. Revert PR from production
3. Make new PR against main and follow developer workflow for production TY24 above

Option 2: Set main as the production TY24 branch and create a long-term "future features" branch for all TY25+ work and merge it back into main

Branches

• main: The main production branch consisting of only production TY24 code, to be deployed to taxpayers in production during FS25 on a weekly basis via release branches
• future: The long-running branch consisting of only future features TY25+ code, not to be deployed to taxpayers in production during FS25

Releases and Deployment

• Cut releases from main
• Deploy from main
• Reserve a lower environment for regular dpeloyments from future for testing future features
• Continue these two branches throughout the year
• When it is time to cutover to TY25 (December 2025 or January 2026), fork a new main branch from future and continue the same processes for the next tax year

Developer workflows

The first step is to identify whether the work is destined for the current production branch, or whether it is work that is only for future tax years.

For production TY24

1. Check out main branch
2. Make PR against main branch
3. Merge into main branch
4. Create a second PR from the main branch into future and resolve conflicts if needed. We are unable to automate this step at this time, but would like to merge into main on every PR in order to make the conflict resolution easier.
   • Note: Regular merge (not "Squash and Merge") is recommended here

For future features

1. Check out future branch
2. Make PR against future branch
3. Merge into future branch

Error workflow

If a change is accidentally merged into future

1. Revert PR from future
2. Make new PR against main and follow developer workflow for future features

If a future feature change is accidentally merged into main

1. Notify release manager in the event the change might be destined for deployment and coordinate as needed
2. Revert PR from main
3. Make new PR against future and follow developer workflow for future features

Option 3: Continue with one main branch and use feature flags to control production functionality

Two technical prerequisites are required for this option that do not exist today:

1. Ability to have multiple tax years exist in the codebase simultaneously because the repository will not have a way of separating one tax year from another via branches. This functionality is currently planned for 2026, not 2025.
2. Robust feature flagging: Because there will only be one single main branch that is deployed to production, we need to have a feature flag system we are confident in to ensure that future features do not accidentally launch to taxpayers ahead of schedule when they are not fully complete.

Branches

• main: The evergreen branch consisting of both future features and production TY24 code. This branch is to be deployed to taxpayers in production during FS25 on a weekly basis via release branches

Releases and Deployment

• Cut releases from main
• Deploy from main
• When it is time to cutover to TY25 (December 2025 or January 2026), no actions are necessary because there is no reconciliation / update of branches needed, there is only one main branch

Developer workflows

For production TY24

1. Check out main branch
2. Make PR against main branch
3. Merge into main branch

For future features

1. Check out main branch
2. Make PR against main branch with a feature flag that controls whether taxpayers will have access to the feature in production (for future features, this should likely be set to OFF)
3. Merge into main branch

Error workflow

If a change is accidentally merged into main

1. Revert PR from main
2. Make new PR against main and follow developer workflow for production TY24 above

Decision Outcome

Chosen option: Option 1: Set main as "future features" branch for all TY25+ work and create a long-term production TY24 branch and merge from production into main in order to minimize the risk of future featues merging into the production branch by mistake. This option will maintain stability in production for our taxpayers, but will result in slightly more friction in the TY24 developer workflow.

Pros and Cons of the Options

Option 1: Set main as "future features" branch for all TY25+ work and create a long-term production TY24 branch and merge from production into main

+

• Lower risk of future features slipping into production because main as "future features" branch is the default branch

-

• Changes to devops workflow for releases and deployment are required because we will now be deploying from production
• Higher risk of TY24 changes being made on main instead of production because main is still the default. Developers working on TY24 will need to consciously switch over to the production branch, but mistakes on the main branch will not lead to taxpayer impact since main is not being deployed to production
• Breaks the principle that main is always deployable

Option 2: Set main as the production TY24 branch and create a long-term "future features" branch for all TY25+ work and merge it back into main at the end

+

• main continues to be the source of truth for production code and is deployable to production
• No change to devops workflow for releases and deployment, we continue to deploy from main

-

• Higher risk of future features accidentally slipping into main since it is still the default branch, which may lead to production issues with taxpayers
• End of season switchover is a little wonky as future becomes main and a new future is created

Option 3: Continue with one main branch and use feature flags to control production functionality

+

• No change to developer workflow in either case of making production TY24 changes or future feature changes
• No change to devops workflow for releases and deployments

-

• Will require additional engineering lift to complete the technical prerequisites of supporting multiple tax years at once and building out the feature flag system, that is unclear we have time for before January 2025

Background information

• Our team is currently using Github flow
• Some additional git workflows considered for inspiration were Gitflow and Gitlab flow, neither of which perfectly met our needs in a simple way