Add backports wiki entry. #109
Conversation
| ## Create the backport branch | ||
|
|
||
| The backport branch needs to be based on the most recent release tag in the series. | ||
| It must be named so it matches `v*.x`, e.g. `v0.2.x` or `v1.x.x`. |
There was a problem hiding this comment.
We could probably just do v1.x once we've hit semver major?
There was a problem hiding this comment.
As far as the matching goes, yes, it supports it by design. Visually in a list of branches I would prefer to see v1.x.x but it's such a tiny detail that I certainly don't hold any strong opinion on that.
| ## Forward-porting the changelog | ||
|
|
||
| After a backport release has been published, its changelog section should be added to the `main` changelog. | ||
| Insert it into the correct middle spot, ordered based on the version number. |
There was a problem hiding this comment.
Some of our changelogs use release links like compare/v0.3.1..v0.4.0 (whereas Color links directly to the GitHub release). For those items, we need to be sure that the "prior" is based on the last version of the previous series which was released from main.
The argument for doing things that way is that it surfaces actually new information (whereas the release just rehashes the content from the CHANGELOG, plus the new contributors).
This is something where standardising either way is fine by me, as the release will still have a full content link.
There was a problem hiding this comment.
Good catch. I agree that surfacing new information makes more sense, so we should standardize on the compares.
There was a problem hiding this comment.
Can we also talk about how deleting old backport branches is an expected pattern, as they can be trivially recovered from the tag, and suggest a level of maintenance to that branch which doesn't exist.
I'd argue for only keeping a backport branch open for the "current" release series (in the future, we could extend this to any active LTS series, if it were specifically funded).
(This isn't a decree of our process, but putting into words the process I had assumed - open to discussion)
There was a problem hiding this comment.
What is the value of deleting old backport branches? They seem useful as a record of "the latest version in a series", and there seems to be little cost to keeping them.
There was a problem hiding this comment.
It can be trivially recovered by only those with appropriate GitHub access. Having the branch already exist would allow for a drive-by contribution to an old series.
If we want to enable that sort of potential, then having the branches exist would be good. However, if we want to purposefully make backports a rarer thing that requires more steps by more privileged people then deleting makes sense.
I guess from our resource constraint point of view, we should limit scope and heavily favor main. So deleting makes sense for now.
Probably still worth limiting the backport branch deletion rights to admins. So we can be more sure that a tag has been created.
There was a problem hiding this comment.
"reducing maintenance burden" by adding more administrative tasks is... classic linebender.
There was a problem hiding this comment.
I think the idea is that we don't want to spend any effort on reviewing PRs for old series if we can help it. So by deleting the branches we signal it very clearly that we don't want those PRs. So a bit of extra work to delete it, to save the work of saying no to people later.
I would slightly prefer to keep the branches around myself, but I'm also fine with deleting them if we really want to promote focus on main.
There was a problem hiding this comment.
Concretely, until we backport to a series, we won't have the v0.4.x branch, which means that the "backport branches as a record of the most recent changes in a series" isn't actually a use case they can fulfil.
If we decided we want something to serve that purpose, and to have release branches for each series, that's fine, and I'd be happy for you to advocate for that @nicoburns. But that isn't a role that backport branches as we currently use them serve. Doing so would be making a tradeoff between "branch containing most recent release of a series" and "potential attempts to contribute fixes to places we don't want to spend effort on". But at the moment, we don't meaningfully get the former, so it's all downside.
Fwiw, I'm not opposed to keeping a branch per release around, if it provides value. But that is still a different conversation to the one we're having here.
Fwiw, I wasn't trying to say we should always immediately delete a backport branch - I was saying that we can delete backport branches for old series.
E.g. if we've just released v0.3.1, and need to release v0.3.2, I wouldn't expect us to delete the v0.3.x branch. But when we have released v0.4.0, the v0.3.x branch then definitely serves no purpose (except the in exceptional circumstances where something is on fire due to an old series).
There was a problem hiding this comment.
Alright I softened the language a bit to make it clear that we won't always immediately delete it.
content/wiki/backports.md
Outdated
| Note that the `v0.3.0` link definition must not be changed. | ||
| `v0.2.3` continues to be the valid starting point because it was the last release in `main` before `v0.3.0`. | ||
|
|
||
| ```md | ||
| [0.3.0]: https://github.com/linebender/color/compare/v0.2.3...v0.3.0 | ||
| ``` |
There was a problem hiding this comment.
IIUC, this 0.3.0 link actually only exists in the changelog to be forward-ported, right?
That's pretty minor in the scheme of things, though.
There was a problem hiding this comment.
Right, it doesn't exist in this branch. I'll remove it and open a different PR for having this info for the changelog in general.
Here in the Parley repo we've used the tag links, but those now just get you the same changelog entry. Instead, [we want to link to the git compare page](linebender/linebender.github.io#109 (comment)) to see all the commits for the release. Also adds the missing link definition for v0.5.0.
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, and0.3.x. While the last two both make it clear what series they are for, I went withv0.4.x(andv4.x.x) for the standard because:v*.xvs*.x)v0.4.4andv0.4.5will be in thev0.4.xbranchBranch 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.