Skip to content

Commit df62863

Browse files
authored
Add backports wiki entry. (#109)
We're pretty solidly in the business of doing backports now, so I think it's time we properly standardize it. It'll make understanding all of this easier across repos, and the wiki entry will also make it easier to do in an urgent situation. I based this on how we've been doing it thus far, with no major changes. Some things worth pointing out: ### Branch naming We've historically used `latest`, `v0.4.x`, and `0.3.x`. While the last two both make it clear what series they are for, I went with `v0.4.x` (and `v4.x.x`) for the standard because: * We get to have a more specific pattern in branch protection (`v*.x` vs `*.x`) * It's closer to the tags, so `v0.4.4` and `v0.4.5` will be in the `v0.4.x` branch ### Branch protection Standardizing will allows us to set up automated rule checking. We'll allow commits to the backport branch via PR only. Review required. CI pass required. There are some nuances to note though. In order to support optionally choosing **Rebase and merge** for the cherry picked commits (*while not wanting it for everything else, like potential custom new code*) we won't be using merge queues for the backport branches. This should be fine, because the backport branches are likely to see very low PR traffic. To ensure that the verification is still the same, the backport branch PRs will be required to be up-to-date. No stale base. Which should also be fine, because, again, low PR traffic. The only technically required CI job will be *formatting*, every other job's result status needs to be verified by the humans involved. The allows us to cut down on administrative work. By only requiring *formatting* we can export/import a single universal backport branch ruleset across repos. Otherwise we would need either per-repo rulesets (like we already do for `main`) and constant backporting of all CI changes to all backport branches, or alternatively, per-branch rulesets to avoid having to backport all CI changes. None of it is very appealing. So let's try human attention for now.
1 parent e43289f commit df62863

File tree

1 file changed

+82
-0
lines changed

1 file changed

+82
-0
lines changed

content/wiki/backports.md

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
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

Comments
 (0)