Skip to content

Add backports wiki entry. #109

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
May 21, 2025
Merged

Add backports wiki entry. #109

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
cc74537
Add backports wiki entry.
xStrom May 19, 2025
71df5c6
Add a note about `main` branch compare links.
xStrom May 20, 2025
27992b5
Remove incorrect note.
xStrom May 20, 2025
cca3211
Add section about branch lifecycle.
xStrom May 20, 2025
9fb63fb
Soften the language around deleting branches.
xStrom May 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 82 additions & 0 deletions content/wiki/backports.md
View file
Open in desktop
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"reducing maintenance burden" by adding more administrative tasks is... classic linebender.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alright I softened the language a bit to make it clear that we won't always immediately delete it.

Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
+++
title = "Backporting in Linebender projects"
+++

## When to backport

Generally we publish the latest state of the `main` branch.
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`.
That's when we need to create a backporting branch to achieve that goal.

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.
Make sure you modify the commands based on your actual versions.

## 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`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could probably just do v1.x once we've hit semver major?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

This branch will be used for all future releases in this series.

```sh
git checkout -b v0.2.x v0.2.3
```

Then push it to the Linebender GitHub repository.

```sh
git push --set-upstream origin v0.2.x
```

## Committing changes to the backport branch

All changes need to go through our usual review process via GitHub pull requests.

Create a working branch based on the backport branch.

```sh
git checkout -b my-changes v0.2.x
```

Then make your actual changes and open a pull request which targets the backport branch instead of `main`.

## Cherry picking vs. new changes

If the desired changes already exist in `main` or another backport branch, then those commits should be cherry picked.
The changelog entries must go into the *Unreleased* section of the backport branch's `CHANGELOG.md`.
Open a pull request targeting the backport branch with one or more cherry picked commits, their changelog entries, and no other changes.
Once the pull request has been approved, it must be merged using the **Rebase and merge** option on GitHub.

All other changes, including any final release preparation commits, need to be separate from any cherry picked pull requests.
Once these pull requests have been approved, they must be merged using the **Squash and merge** option on GitHub.

## Changelog modifications

In addition to the usual changes, the changelog header section must be updated as follows:

```diff
- The latest published Color release is [0.2.3](#023-2025-01-20) which was released on 2025-01-20.
- You can find its changes [documented below](#023-2025-01-20).
+ This is the backport branch for Color 0.2.x.
+ For the latest releases, check the [changelog on `main`](https://github.com/linebender/color/blob/main/CHANGELOG.md).
+ 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.
+ You can find its changes [documented below](#024-2025-05-19).
```

Plus the *Unreleased* link in the footer must compare this specific backport branch:

```diff
- [Unreleased]: https://github.com/linebender/color/compare/v0.2.4...HEAD
+ [Unreleased]: https://github.com/linebender/color/compare/v0.2.4...v0.2.x
```

## Forward-porting the changelog

After a backport release has been published, its changelog section must be added to the `main` changelog.
Insert it into the correct middle spot, ordered based on the version number.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch. I agree that surfacing new information makes more sense, so we should standardize on the compares.


## Branch lifecycle

Due to resource constraints we want to promote development in `main`.
We only want to do backporting in exceptional circumstances.
This means that once a backport release has been made and the correct git tag has been created, we might delete the backport branch.
If another backport release needs to happen in the same series, then the branch may have to be re-created from the aforementioned tag.