|
| 1 | +--- |
| 2 | +title: Support branches |
| 3 | +weight: 2 |
| 4 | +--- |
| 5 | + |
| 6 | +# Support branches |
| 7 | + |
| 8 | +We use support branches when we want to: |
| 9 | + |
| 10 | +- publish a new release of previous major versions of GOV.UK Frontend |
| 11 | + |
| 12 | +- publish a 'hotfix' release of GOV.UK Frontend without including other unreleased changes on the `main` branch |
| 13 | + |
| 14 | +Once a support branches has been created it should be maintained in parallel to the `main` branch. The support branch will never be merged into the `main` branch. |
| 15 | + |
| 16 | +Support branches have the same branch protection rules as the main branch. Any changes made in a support branch should be raised as Pull Requests. |
| 17 | + |
| 18 | +## Using support branches for previous major versions |
| 19 | + |
| 20 | +We can use support branches to publish new releases of a previous major version. |
| 21 | + |
| 22 | +For example, if we found a bug that affected all versions of GOV.UK Frontend between v4.6.0 and v5.1.0, we might choose to release a new version of v4 as well as a new version of v5 so that users stuck on v4 can get the fix without needing to upgrade to v5. |
| 23 | + |
| 24 | +We might also use a support branch so that we can continue to release when we have unreleased breaking changes on the main branch during the initial development of a new major version. |
| 25 | + |
| 26 | + |
| 27 | + |
| 28 | +<!-- |
| 29 | +gitGraph |
| 30 | + commit |
| 31 | + commit tag: "v4.6.0" |
| 32 | + branch "support/4.x" |
| 33 | + checkout "main" |
| 34 | + commit |
| 35 | + commit |
| 36 | + commit |
| 37 | + commit tag: "v5.0.0" |
| 38 | + commit |
| 39 | + checkout "support/4.x" |
| 40 | + commit |
| 41 | + commit tag: "v4.6.1" |
| 42 | + checkout "main" |
| 43 | + commit |
| 44 | + commit |
| 45 | + commit tag: "v5.0.1" |
| 46 | + checkout "support/4.x" |
| 47 | + commit |
| 48 | + commit tag: "v4.6.2" |
| 49 | +--> |
| 50 | + |
| 51 | +There should only be one support branch for each previous major version. The support branch should be named using only the major version number, for example the branch name for the v4 major release would be called `support/4.x`. |
| 52 | + |
| 53 | +Because the support branch will never be merged back into the main branch, any changes that affect both current and previous major versions require multiple pull requests -- one for each support branch for each of the affected previous major versions, and one to fix it on the main branch for the current major version. |
| 54 | + |
| 55 | +## Using support branches for hotfixes |
| 56 | + |
| 57 | +If we discover a bug in GOV.UK Frontend that we urgently need to fix, we can use a support branch to release just the fix without including other unreleased changes on main. |
| 58 | + |
| 59 | +(Ideally the main branch is always kept in a releasable state, but we might still prefer to release a set of changes together to provide a more coherent release, or hold off releasing a change until we have accompanying documentation ready to go.) |
| 60 | + |
| 61 | +Support branches should only be used to fix bugs, not to introduce new features. |
| 62 | + |
| 63 | + |
| 64 | + |
| 65 | +<!-- |
| 66 | +gitGraph |
| 67 | + commit |
| 68 | + commit tag: "v4.6.0" |
| 69 | + branch "support/4.6.x" |
| 70 | + checkout "main" |
| 71 | + commit |
| 72 | + commit |
| 73 | + commit |
| 74 | + checkout "support/4.6.x" |
| 75 | + commit |
| 76 | + commit tag: "v4.6.1" |
| 77 | +--> |
| 78 | + |
| 79 | +The support branch should be named using the major and minor version number of the previous release. For example, if the last release was v4.6.0 and we expect the unreleased changes on the main branch to go out as part of v4.7.0, the support branch should be named `support/4.6.x`. |
| 80 | + |
| 81 | +Because the support branch will never be merged back into the main branch, you may need to raise a second pull request to make the same changes to the main branch, otherwise the bug may be reintroduced in the next release. |
| 82 | + |
| 83 | +## Creating a support branch |
| 84 | + |
| 85 | +If the support branch doesn't already exist, you can create it by following these steps. |
| 86 | + |
| 87 | +1. Make sure you have all tags in our local version of the repo by running `git fetch --all --tags --prune` |
| 88 | + |
| 89 | +2. Run `git checkout tags/v<LAST RELEASED VERSION NUMBER> -b <NAME OF SUPPORT BRANCH>`. For example, `git checkout tags/v4.6.0 -b support/4.x` |
| 90 | + |
| 91 | +3. Push the support branch to GitHub. You should push the branch without making any further changes. GitHub will automatically enforce the expected branch protection rules as long as the branch is named correctly. |
| 92 | + |
| 93 | +## Making changes to a support branch |
| 94 | + |
| 95 | +Before making changes: |
| 96 | + |
| 97 | +1. Check out the support branch |
| 98 | + |
| 99 | +2. Run `nvm use` to make sure you're using the right version of Node.js and npm, then run npm install |
| 100 | + |
| 101 | +3. Given there may be significant differences between the development environment in main and the support branch, run the tests to make sure everything works as expected before making changes |
| 102 | + |
| 103 | +4. Create a new branch based on the support branch which you'll use to raise the Pull Request |
| 104 | + |
| 105 | +If you are releasing a fix for a bug that has already been fixed on the main branch, you can then cherry-pick the commits that fix the bug onto your new branch. |
| 106 | + |
| 107 | +Otherwise, make whatever changes are required and then commit your code changes, before raising a Pull Request with the support branch as the target branch |
| 108 | + |
| 109 | +Remember that you might also need to make the same change to the main branch or other support branches. |
| 110 | + |
| 111 | +## Releasing from a support branch |
0 commit comments