|
| 1 | ++++ |
| 2 | +title = "Backporting in Linebender projects" |
| 3 | ++++ |
| 4 | + |
| 5 | +## When to backport |
| 6 | + |
| 7 | +Generally we publish the latest state of the `main` branch. |
| 8 | +However, if `main` has breaking changes or we want an older release series to receive some non-breaking changes, then we can't just publish `main`. |
| 9 | +That's when we need to create a backporting branch to achieve that goal. |
| 10 | + |
| 11 | +The example commands below are based on Color and its `main` already being at `v0.3.1` when we also wanted to release a `v0.2.4`, with `v0.2.3` being the latest in that series. |
| 12 | +Make sure you modify the commands based on your actual versions. |
| 13 | + |
| 14 | +## Create the backport branch |
| 15 | + |
| 16 | +The backport branch needs to be based on the most recent release tag in the series. |
| 17 | +It must be named so it matches `v*.x`, e.g. `v0.2.x` or `v1.x.x`. |
| 18 | +This branch will be used for all future releases in this series. |
| 19 | + |
| 20 | +```sh |
| 21 | +git checkout -b v0.2.x v0.2.3 |
| 22 | +``` |
| 23 | + |
| 24 | +Then push it to the Linebender GitHub repository. |
| 25 | + |
| 26 | +```sh |
| 27 | +git push --set-upstream origin v0.2.x |
| 28 | +``` |
| 29 | + |
| 30 | +## Committing changes to the backport branch |
| 31 | + |
| 32 | +All changes need to go through our usual review process via GitHub pull requests. |
| 33 | + |
| 34 | +Create a working branch based on the backport branch. |
| 35 | + |
| 36 | +```sh |
| 37 | +git checkout -b my-changes v0.2.x |
| 38 | +``` |
| 39 | + |
| 40 | +Then make your actual changes and open a pull request which targets the backport branch instead of `main`. |
| 41 | + |
| 42 | +## Cherry picking vs. new changes |
| 43 | + |
| 44 | +If the desired changes already exist in `main` or another backport branch, then those commits should be cherry picked. |
| 45 | +The changelog entries must go into the *Unreleased* section of the backport branch's `CHANGELOG.md`. |
| 46 | +Open a pull request targeting the backport branch with one or more cherry picked commits, their changelog entries, and no other changes. |
| 47 | +Once the pull request has been approved, it must be merged using the **Rebase and merge** option on GitHub. |
| 48 | + |
| 49 | +All other changes, including any final release preparation commits, need to be separate from any cherry picked pull requests. |
| 50 | +Once these pull requests have been approved, they must be merged using the **Squash and merge** option on GitHub. |
| 51 | + |
| 52 | +## Changelog modifications |
| 53 | + |
| 54 | +In addition to the usual changes, the changelog header section must be updated as follows: |
| 55 | + |
| 56 | +```diff |
| 57 | +- The latest published Color release is [0.2.3](#023-2025-01-20) which was released on 2025-01-20. |
| 58 | +- You can find its changes [documented below](#023-2025-01-20). |
| 59 | ++ This is the backport branch for Color 0.2.x. |
| 60 | ++ For the latest releases, check the [changelog on `main`](https://github.com/linebender/color/blob/main/CHANGELOG.md). |
| 61 | ++ The latest published Color release in the 0.2.x series is [0.2.4](#024-2025-05-19) which was released on 2025-05-19. |
| 62 | ++ You can find its changes [documented below](#024-2025-05-19). |
| 63 | +``` |
| 64 | + |
| 65 | +Plus the *Unreleased* link in the footer must compare this specific backport branch: |
| 66 | + |
| 67 | +```diff |
| 68 | +- [Unreleased]: https://github.com/linebender/color/compare/v0.2.4...HEAD |
| 69 | ++ [Unreleased]: https://github.com/linebender/color/compare/v0.2.4...v0.2.x |
| 70 | +``` |
| 71 | + |
| 72 | +## Forward-porting the changelog |
| 73 | + |
| 74 | +After a backport release has been published, its changelog section must be added to the `main` changelog. |
| 75 | +Insert it into the correct middle spot, ordered based on the version number. |
| 76 | + |
| 77 | +## Branch lifecycle |
| 78 | + |
| 79 | +Due to resource constraints we want to promote development in `main`. |
| 80 | +We only want to do backporting in exceptional circumstances. |
| 81 | +This means that once a backport release has been made and the correct git tag has been created, we might delete the backport branch. |
| 82 | +If another backport release needs to happen in the same series, then the branch may have to be re-created from the aforementioned tag. |
0 commit comments