tools: Add hotfix release script

[beautifulentropy]

The process of creating a new hot fix release is entirely manual and prone
to human error. This script automates a fair bit of the process and includes
detailed instructions for the remaining steps.

Part of #5726

[beautifulentropy]

Thanks for all of the comments @aarongable I think you just made this script a whole lot safer. I went ahead and tested these changes on my boulder fork and they worked perfectly.

[aarongable]

Looks to me like, if we already have a release-branch-YYYY-MM-DD and a release-YYYY-MM-DDa tag from a previous hotfix earlier the same week, then this is going to create a new branch with the a suffix instead of continuing to use the existing branch and just adding new commits and a new tag to it.

[beautifulentropy]

Unless I'm missing something, the way that this is currently written follows the current Boulder Release Process Example:

Later on 2018-01-31 its discovered that the bug in release-2018-01-30, which was hotfixed with release-2018-01-30a is still broken! Uh oh! Since main is dirty, and contains a feature commit not present in release-2018-01-30 or release-2018-01-30a the hotfix must be prepared in a separate branch. @cpu starts a new branch release-branch-2018-01-30a by checking out release-2018-01-30a and pushing it as the release branch.

[beautifulentropy]

Oh, gosh, I think I misunderstood what you were saying here. So, I don't think that this is the case at all. Up on lines 61-63 is where we pull in the information about the the latest tag and the commit associated with it:

print_heading "Fetching details for the most recent release tag"
latest_tag_sha=$(git show-ref --tags | tail -1 | awk '{print $1}')
latest_tag_name=$(git show-ref --tags | tail -1 | awk '{print $2}' | sed 's|refs\/tags\/||')

outputs:

samantha at treepie in ~/repos/myboulder (hotfix-release-script)
$ git show-ref --tags | tail -1 | awk '{print $1}'
9dbbc489ae3252c2f4c75c484d730591da0dfa71

$ git show-ref --tags | tail -1 | awk '{print $2}' | sed 's|refs\/tags\/||'
release-2021-11-30

If we shipped a hotfix, either on main, because main was still clean, or a new branch (e.g. release-branch-YYYY-MM-DDa) because main was dirty, it's fine cause we fetch the latest tag and it's associated commit SHA that we use to create a new release branch.

[beautifulentropy]

Going to replace git show-ref --tags with git ls-remote --refs --tags so that we don't end up with local tags causing a problem.

[aarongable]

Sorry, what I'm trying to say is that I think the release doc is vague or imprecise (and I'm happy to fix that next week!) and that your interpretation of what it says, while I understand how you got there, is not what I intended the last time I edited that section, and is not what we did on that 08-30 branch I referenced above.

We should never have a branch with a letter suffix.

The first time we decide we need a hotfix based on the latest normal release, we should create a new branch named after that release's tag. So when the last normal release was release-DATE, the branch would have a name like release-branch-DATE. Then we cherry pick one or more commits onto that branch, and tag its tip with the hotfix tag release-DATEa.

Then we decide we need another hotfix. We do not create a new branch: we already have one. We cherry-pick one or more commits onto the tip of the same branch. Then we tag the tip of the release branch with the new hotfix tag release-DATEb.

There's never a need to create a second release branch because there's no chance that anything we don't want to release has been landed on the release branch -- only things we specifically want to backport have been cherrypicked and tagged on it.

Basically the bottom line is that: getting the latest tag is good and necessary for computing what the name of the new tag should be. But we don't want to unconditionally create a new branch with essentially the same name -- we only want to do that if this is the first hotfix on top of a normal release. Otherwise we want to strip the letter suffix in order to compute the name of the pre-existing release branch, and check that out instead of creating a new one.

[aarongable]

Looks like this is designed to let you cherry-pick multiple commits onto the release branch? I like it! Two things I'd change:

1. take the list of commits on the command line instead of from stdin
2. only do the push and tag after the very last one

[beautifulentropy]

At present this takes just one cherry-pick. I was mostly going off of experience, but I don't think I've ever had to do more than a single cherry-pick for hotfixes I've done here. I could add some flags and opt parsing to enable what you're asking for in a follow-up commit. How does that sound?

[aarongable]

Ah, I misunderstood. If the goal is to only cherry-pick one commit, then there's no need to have this inside a while loop.

I like the idea of accepting multiple commits to cherry pick (for example: that 08-30 release branch had four commits cherry picked onto it but only two hotfix releases tagged on it). But it's certainly not necessary for v1 of this script.

Either way, I'd still prefer to take the sha1 on the command line rather than stdin so that hotfix release commands can be easily copy-pasted and reviewed for correctness before they're executed.