Advance notice: This article describes an upcoming change to how Gearset pipelines behave. This change is not yet live - and we expect to release this change to the app on the 9th of November
Before you start
Check these things before you create a fix PR:
The feature has left its first environment - While the feature is still in its first environment, Gearset syncs new commits for you. To update these PRs, you can simply commit to the feature branch.
The feature's promotion PR was created in Gearset Pipelines - Gearset is unable to determine the origin of PRs opened outside Gearset Pipelines, including PRs created via Compare and Deploy. These PRs will be seen by Pipelines as being on their initial environment, and so will sync any new changes automatically from the feature branch on that first environment.
The feature isn't in an active release / bundle - Fix PRs can't merge into releases / bundles yet, therefore features merged into these cannot be fixed yet by this flow. Please either remove the feature from the release / bundle to update the feature PR in isolation, or merge the fix PR separately into production. We aim to offer first-class support for releases and bundles in the coming weeks.
Create and promote a fix PR
Step 1: Commit your fix to the feature branch
In your dev sandbox, make the fix. Then commit it to the same feature branch you used for the original feature - don't create a new feature branch. Alternatively, you can commit the changes directly to the feature branch if they are not on your dev sandbox.
Your feature branches represent your changes relative to your pipeline default branch. Creating a new feature branch means that two versions of your changes will exist - which can cause unintended merge conflicts if they have diverged significantly.
If you have force pushed your feature branch and have created a fix, the fix PR will only contain the changes in the new version of your feature branch, and won't revert any commits which you have force pushed out of your new version of the branch. For best results, please try to ensure that all changes are commits to the existing branch rather than modifying branch history.
Step 2: Find the stale promotion PR
In your pipeline, find the feature's promotion PR. Because the promotion branch is now missing your new commit, Gearset marks the PR as stale. The app will alert you that (in order to include those changes in your PR) you will need to create a fix PR:
Step 3: Click Create Fix PR
Fix PRs are created from developer sandboxes. Selecting a feature in your dev sandbox will show where each PR for this feature is currently open.
To create a fix request for a feature, select your feature branch and select Create fix pull request:
Now, the original stale PR will be blocked from promoting until this fix PR fixes the original stale PR.
Important note: You should only create fix PRs from the first environment in your pipeline. You are unable to create fix PRs directly targeting the currently open feature - in this scenario we recommend instead creating a hotfix feature.
Step 4: Check the fix PR details
Gearset fills in the fix PR for you. Check these details:
The title is pre-filled as
Fix for <feature-branch>.The tests and deployment steps from the feature PR are already attached.
You can edit the title and description of fix PRs here (similar to other PR types).
*Gearset Summarise Changes feature used for PR description
If you need additional pre/post deployment steps, add these to the original feature. They'll be carried over to the fix PR when this is created.
Step 5: Create the fix PR
Create the fix PR. Gearset links the two PRs:
The stale promotion PR now shows
This pull request is blocked by a fix. Cannot promote until fix PR <number> is merged.The fix PR links back to the promotion PR it's blocking.
Step 6: Promote the fix PR
Promote the fix PR through your pipeline in the same way as any other PR. Gearset copies its tests, deployment steps, and other settings into each PR it propagates into.
Step 7: Check that the fix merged into the promotion PR
When the fix PR reaches the environment where the feature's promotion PR is waiting, Gearset merges the fix into the promotion branch for you. It doesn't open a new PR there; instead, your existing feature promotion PR should no longer be blocked from promoting, and you should see your fix PR's changes on the feature PR.
Step 8: Promote the feature
When validation has re-ran and has passed, promote the feature's promotion PR as normal. Your fix now moves forward with the feature.
Abandon a fix PR
If you don't need a fix PR anymore, you can abandon the PR itself in VCS. However, doing so will not unblock the stale PR from promotion. Abandoning a fix PR will also not sync the promotion branch and feature branch, and extra commits made on the feature branch will not be deployed when the feature is merged. A new fix PR would still be required in this scenario.
Instead, we recommend abandoning the fix from within Gearset.
Step 1: Open the fix PR or the stale promotion PR
You can abandon a fix from the fix PR itself.
Select the red trash icon in the top right to abandon the fix PR:
Step 2: Abandon the fix PR
Abandon the fix. This will close all open fix PRs for the selected feature in your version control system.
Abandoning a fix PR in VCS
If you do abandon a fix PR in your VCS, the feature PR will still be blocked by the fix, despite no fix PR existing for the chosen feature. In this scenario we will flag this on the PR itself as shown below:
In this scenario, you can unblock the PR by clicking Abandon fix on the blocked feature PR itself, and following the steps outlined above. Alternatively, you can still create a new fix PR in this scenario by selecting Create fix pull request on your dev sandbox, and this new fix PR will behave in the same way as the closed fix PR.
Things to know
Don't merge stale PRs in your version control system. Gearset only blocks promotion inside Gearset, so a merge done directly in your VCS skips the fix.
Don't change the promotion branch outside Gearset. If you force push or change it in your VCS, Gearset may not keep those commits when that feature promotes through the pipeline (since we use the feature branch as the source-of-truth for your feature).
DevOps Performance Tracking: Fix PRs are treated identically to feature PRs ain the DevOps performance and Dora metrics views. We do not explicitly mark the features or fix PRs as containing bugs as a part of this process.