# Project Release Workflow

This guide assumes you are working off of a flow that involves feature and fix branch merge requests targeting a longer running release branch (release/next) that is merged to main at regular intervals such as the end of a sprint.

# 1. Merge request (MR/PR) created from release branch into main

The next release MR should be created at the start of the sprint and be named after the project itself, e.g. if the project is named SecurityModel then the MR title should be SecurityModel next release or SecurityModel sprint 4 release.

The creation of this MR should spawn a review app that is incrementally updated each time a commit is added to the release/next branch.

The next release MR should NEVER squash commits going into main so that the commit history can be preserved. The release/next branch should always be in a state that main can be fast-forwarded to it. If new commits have been added to main between release cycles then release/next should be rebased if it can be done cleanly, a merge commit can be acceptable if necessary.

Merge requests that target release/next, however, should ALWAYS squash commits going in. This is to prevent the commit history on release/next (and eventually main) from becoming too noisy.

# 2. MR from release branch is approved

At the end of the sprint cycle the repository maintainer must get approval from another user with approval rights for main, preferrably from someone who is familiar with the tech stack and project.

Depending on the results of code scanners, approval from InfoSec may be required. At this time, any merge requests going into protected branches that have critical, high, or unknown vulnerabilities require InfoSec approval.

# 3. MR from release branch is merged to main

Once appropriate approvals have been given, the MR can be merged to main.

This should start a pipeline that results in release notes being generated from the commit history and appended to the CHANGELOG.md file and a new commit and git tag being created. The semantic release process should read the commit history for this release and determine which version segment should be incremented (major, minor, or patch).

If the pipeline fails for any reason and a new tag is not created then the issue must be addressed before the release process can go any further.

# 4. Update release branch with new commit from main

The semantic release process adds a new commit directly to the main branch. This commit must be pulled in to release/next in order for a fast-forward merge to be possible for the next release cycle.

1. git checkout release/next
2. git pull
3. git pull origin main
4. git push

Note: Pulling from main should also fetch the most recent tag. If it does not, it can be explicitly fetched with git fetch origin --tags.

# 5. Create release branches for qa/prod deploys

Now that main and release/next are in sync and a new git tag has been created, we can begin to set up the releases for the qa and production deployments. The process for creating these branches is the same for both environments, though the actual deployments may differ.

Environment specific releases are named after the tag being deployed and the environment it is being deployed to.

1. Start by switching to the qa branch and updating it from the remote.
   • git checkout qa
   • git pull
2. Next, create the release branch for the qa environment and merge in the tag. (note that the branch name matches the tag being merged in)
   • git checkout -b release/v1.1.0_qa
   • git merge v1.1.0
3. Finally, push that branch to the remote
   • git push -u origin release/v1.1.0_qa
4. Repeat this process for prod branch and any other environments

# 6. Create MRs to qa/prod branches on remote

Now that release branches have been pushed to the remote, merge requests into those environments can be created. Like their corresponding branches, these MRs should be titled after the tag and environment they target, e.g. if the project is named SecurityModel, the tag being deployed is v1.1.0, and the target deployment environment is qa, then the MR title should be SecurityModel v1.1.0 release to QA.

Like main, merges to these branches should always be fast-forwarded and never squashed. Though it is not strictly necessary to do, it is best practice for these branches (or any protected branches) to have the same commit history as main.

# 7. MRs to qa/prod approved

Currently, merge requests to the qa environment require approval from someone in QA team, preferrably a manager. Merge requests to prod require the same approval rights as main.

Once these MRs are approved by the appropriate parties, they can be merged into their respective branches.

# 8. Release to environments

Releases for qa and similar environments may differ from releases to prod environment

# QA environment release

After approval has been given on the MR targeting the qa environment it can be merged. The merge to qa branch should trigger an immediate, automated release to the qa environment.

# PROD environment release

Merges to prod do not necessarily trigger an immediate, automated release to the prod environment. These releases should require manual intervention from the architecture team and should be accompanied by an associated and approved change request.

# 9. Cleanup

Now that releases are complete we can clean up.

1. Delete release branches on remote
   • These branches may be protected and require deletion at the source, you may not be able to delete them from your terminal
2. Delete local release branches
   • git branch -d release/v1.1.0_qa
   • git branch -d release/v1.1.0_prod
3. Prune local tracking branches for remote branches that have been deleted
   • git remote prune origin