Creating a Hotfix

From time-to-time there may be an occasion where a hotfix is needed to address a security vulnerability or other critical issue. In general addressing such issues would happen via the standard development workflow. However, if the dev branch has progressed beyond the latest release and is not in a releasable state, a hotfix is needed to address the issue.

Communicate and Triage

When the critical issue is discovered the development team along with other relevant stakeholders should the review issue and decide the appropriate course of action. If an immediate release is required the method (standard or hotfix) should be determined. The service org should be consulted to determine the appropriate time for the release to minimize disruptions.

Creating the Hotfix branch

When implementing a hotfix, a hotfix branch must be created off the latest released tag.

# update from project repository
git fetch {project_remote}

# checkout the latest released tag
git checkout {tag_name}

# create a new hotfix branch from the tag
git checkout -b hotfix

# push the hotfix branch to project repository
git push {project_remote} hotfix

Fixing the issue

Only required changes should go into the hotfix branch. New features and extraneous chores should be left for a standard release.

1. Create a new branch from the hotfix branch
2. Make the necessary fixes
3. Submit a pull request against the hotfix branch
4. Review and test the changes
5. When ready, merge the pull request into the hotfix branch

Changing the base branch

If the fix was started off of a branch other than hotfix, e.g. dev, the base of the branch can be switched. This is likely to happen in the case where a critical vulnerability is reported and addressed by an automated dependency pull request. If a pull request was already made, navigate to the pull request page in GitHub and change the base branch to hotfix. Next you’ll locally change the base of the branch and push back up to the pull request's branch. (See: Moving a git branch to a new base)

# make sure your local dev branch is up-to-date
# fetch latest changes from the project repository
git fetch {project_remote}

# make sure there are no local changes in dev that aren’t in the project repository
git log dev ^{project_remote}/dev

# make sure you’re on the local dev branch
git checkout dev

# merge changes from the project repository into the local dev branch
git merge {project_remote}/dev

# pull down the pr branch, this may either be in the project repository or in a fork
git fetch {pr_remote}

# checkout the PR’s branch
git checkout {pr_branch}

# change the base branch, in this case from dev to hotfix
git rebase --onto hotfix $(git merge-base dev @)

# push back up to the PR’s remote
git push {pr_remote}

At this point the pull request on GitHub should be automatically updated and you’ll see that the correct commits are reflected.

Releasing

Release commit

For hotfixes you’ll need to manually create the release commit, as the automated releases are based off of the dev branch.

See a chore(release) commit from a prior release to know what to update. It’ll likely include:

• .release-please-manifest.json Do Not Update
• CHANGELOG.md
• composer.json

NOTE: Do not update the .release-please-manifest.json file. Leaving it as is will allow release-please to keep generating the proper next version with the full change log from the last non-hotfix release.

Make the appropriate changes in a new chore(release) commit and push to the hotfix branch.

1. Create a new branch from the hotfix branch
2. Make the necessary fixes
3. use a commit message like "chore(release): release {version}"
4. Submit a pull request against the hotfix branch
5. Review and test the changes
6. When ready, merge the pull request into the hotfix branch

To create the release

• Go to the releases page
• Click "Draft a new release"
• Use "hotfix" as a target
• Set the new tag name to the appropriate version number (e.g. v1.7.1) and and allow it to create a new tag on publish
• Set the tag name as the "Release title"
• Add the release notes, see previous releases for what to include. Should be the same as what was added to the CHANGELOG.md
• Check “Set as the latest release”
• When everything looks good, click “Publish release”

Merging

On release, the tag should be automatically merged into the staging branch. After staging has been successfully deployed, quickly test to make sure that it is in working order. If that checkout merge the tag into Production and Dev.

Deleting the hotfix branch

After all of the merging has been completed and deployed successfully, the hotfix branch can be removed. The hotfix branch is deleted to reduce confusion and keep the repository clean. The release tag should remain as it has been merged into the other branches.