How to apply hotfix for multiple past releases using Github Flow

Question

Were using GitHub flow for our opensource project, but I don't understand how to handle hotfixes when there are multiple releases branches containing the bug.

Lets say we have versions 0.0.1, 0.0.2 released and supported by me and another developer.
Were currently working on a new version 0.0.3 which is in master.
master is stable but not ready since we have a few more features to implement before we can commit to version 0.0.3.

Say we found a critical bug on 0.0.1 that applies for 0.0.2 and 0.0.3 (which hasn't been deployed yet) too.

What is the steps to apply hotfix for this kind of scenario ?
Do we branch out of master and merge the fix to every release ?
Do we version bump each release (v0.0.1b for example) ?

Thanks !

Answer 1

Here's a basic plan. Switch to v0.0.1 detached, make the needed fixes, add and commit. Tag that commit, e.g. v0.0.1b. Now, in turn, switch to each of the other release tags and cherry-pick v0.0.1b onto it and tag it as well. Finally, switch to main and any other existing branches that need this fix and cherry-pick v0.0.1b onto each of those as well.

That was the TL:DR. Now let's talk about why this could be a thing to do, and why it's so obvious when you know what Git is, what a branch is, what a tag is, and what a merge is.

Git is a directed acyclic graph consisting entirely of commits. Each commit is a snapshot of the entire state of the project at a given moment. Each commit has at least one parent, which is what gives the graph its directionality. Git does not contain any diffs or even really any history; the history story is simply a spontaneous traversal of the graph, starting at any given commit and moving to its parent, the parent of that, the parent of that, and so on — the parent chain.

A branch is nothing but a name for one commit. It does have two rather remarkable properties, though: (1) if you are "on" a branch (i.e. that branch is HEAD) and you make a new commit, the branch name is automatically transferred to that commit; and (2) a commit named by a branch will never die, and neither will its parent, nor its parent, and so on. In other words, branches are what keeps the commits in the repo alive.

A tag is similar to a branch but without the first magical property; it's a name for a commit, it keeps that commit alive (along with its parent chain), but it never moves from its commit (unless you move it, but you probably wouldn't do that, as the purpose of the tag is mark forever a place in the history).

A merge is a commit that Git itself makes. It does this by applying merge logic to two commits, the one that is HEAD at the time of the merge and the one that is being merged. This merge logic, simply put, involves calculating the diffs from an earlier parent, the merge base, and applying both diffs simultaneously to the HEAD.

Now then! You've got your v0.0.1 commit, and guess what, it's faulty. So you need a place to create a fix. You are going to have construct a piece of the history tree yourself, in a controlled and meaningful way. How should the new topology look? Well, in the first place, you want to keep v0.0.1 but you also want a new commit which is just like it except that it incorporates what you now know are the needed fixes. So you switch to v0.0.1, which is possibly only by asking for a detached head, make the changes, and add-and-commit. You now have an excellent commit, but guess what? If you don't do something to preserve it, that commit will die, because it is not named by a branch or a tag and it has no child — all of the things that would keep a commit alive. So you tag it, and now it will live forever. I'll call the tag v0.0.1b but it's up to you how you want to handle this naming.

Now let's turn to your next release, v0.0.2. You want to make the same changes against it as well. That's merge logic! In particular, you probably want to cherry-pick the commit that you have just created and tagged, the hot fix commit. Why? Well, the merge base used during a cherry-pick is the parent of the cherry-picked commit. So the cherry-pick will create a new commit that expresses the difference between v0.0.1 and the newly created and tagged commit that you made as its child, v0.0.1b. In other words, it will contain the fixes you want! So switch to v0.0.2 (which requires a detached head), cherry-pick v0.0.1b, and don't forget to tag it to keep it alive; let's call this one v0.0.2b.

But we are now waving our hands. Do that for all you pre-existing releases. And then, don't forget to do it for main as well! You want it to have these fixes too, obviously. The only difference is that when you switch to main you are not detached, so you can just cherry-pick v0.0.1b and stop; the job is done. Now go on with life as usual.