Oddities in branching structure

[LiberalArtist]

@benknoble

it took me quite a while to connect the dots to Proposed stable branch discipline

I don't have all of this paged in, but I've got some pointers to discussion that came before that thread. I believe the issue of the current stable branch structure was first raised here:

@LiberalArtist

With the caveat that I don't know how this would work for other aspects of the release process, here's an idea that would make sense to me from a Git perspective, partially inspired by the sort of "soft launch" we tried this release cycle. It also tries to address a much less significant quirk I noticed, which is that the head of the stable branch tends to point to a merge commit like Merge branch 'stable' into release · racket/racket@424d167 · GitHub rather than the commit pointed to by the release tag.

I took a first crack at putting that proposal into practice in Make `release` a descendant of `stable` by LiberalArtist · Pull Request #4460 · racket/racket · GitHub. We picked that back up with:

@LiberalArtist

@jbclements, just wanted to make sure you saw this: Make release a descendant of stable by LiberalArtist · Pull Request #4460 · racket/racket · GitHub

@jbclements

Yes. Did my response (sent on a plane so who knows) actually get to you?

@LiberalArtist

Yes, I've just written back. Tl;dr the simple part should be simple, but you were right about:

@jbclements

One challenge in testing this manual makefile update are that the catalog itself must be available in order to test it, which is why this update occurs after testing is complete.

From the off-list email chain with @jbclements:

@jbclements

D’oh! I can’t accept this PR using the GitHub interface, since merge commits are disabled for our repo in the GitHub settings …

So I decided to just run your commands on my own release branch.

I noticed … [t]he repo graph after the merge with stable is is totally horrible. But AFAICT it’s horrible because of what we’ve done to stable in the past, and not any worse than the existing graph of stable.

We dropped the notion of delaying creation of the Git tag after this comment by @elibarzilay, plus some complications @jbclements pointed out in those off-list emails, so we focused just on organizing the Git history for the release and stable branches:

@LiberalArtist

@elibarzilay

• Re your suggestion of not creating the tag until some testing, the original motivation for creating the tag as soon as the version is bumped (for releases) is to avoid a situation where there are two builds with the same version number that are not the same code, so there's no chance of confusion. There was even at some point a bit in the release where I faked the new version number so I can update things like screenshots (and some Shriram-related things too?). Probably mostly moot now.

This makes sense. (@jbclements also pointed me to some complications off-list.) If we try to revisit this idea next release, one thing I noticed is that release-catalog/scripts/add-tags.rkt at master · racket/release-catalog · GitHub currently creates tags using the GitHub API: maybe creating tags locally could keep some benefits but be more flexible? But I also think it might be a better use of effort to just do as @samth suggested elsewhere:

@samth

In general it seems like we should consider figuring out how to make point releases easier to make, since downstream consumers are unhappy when we change things after the release.

Interestingly, it seems we did discussing merging stable into master in a way that would address the git describe quirk:

@LiberalArtist

@elibarzilay

• By some cosmic coincidence, I went over this branching approach in the last few weeks (due to $work), and implemented roughly the same strategy, automated via a github action. One thing that I've noticed (~two days ago) is that due to merges going only from master to release to stable but not the other way, GH shows stable as being way ahead of master. I figured that an improvement there would be exactly the kind of -s ours fake merge to avoid that confusion.

Interesting! To be concrete, are you suggesting that, after tagging the release and updating stable, we should git checkout master && git merge -s ours stable? That seems like a nice enhancement! In addition to showing which branch is "ahead", it would also record where we were in the history of master when we released a given version.

That is the process illustrated in the last version of a #lang slideshow diagram I made of this process, which I found very helpful in thinking it through: Racket release branch diagram · GitHub

@jbclements raised the point that any merge of stable into master would break the property that master currently has a linear history. The last discussion I found on that is:

@LiberalArtist

Re:

@jbclements

Thinking about this a bit more. I kind of like the fact that currently, the master branch has a single thread. I realize that merge commits that are made with merge -s ours don't represent "real" dependencies, but that's not obvious unless you dig into the commits and see that the merge has no diff. So I'm inclined to drop back to the "merge-with-the-release-branch-when-its-created" strategy. I'd really like to hear from others, though. @samth ? @mflatt ?

I don't have a strong opinion; I can see advantages on both sides. If we did opt to merge stable into master, you have a good point that we should probably edit the commit message to be explicit that it's a "fake" merge.

But actually, I think we don't need to make a final decision until after this release. Once you push v8.7 and stable, we'll presumably see this effect @elibarzilay pointed out:

@elibarzilay

One thing that I've noticed (~two days ago) is that due to merges going only from master to release to stable but not the other way, GH shows stable as being way ahead of master.

If that creates noise in the UI or it otherwise seems desirable to do the "merge-stable-into-master-after-release" variant, we could do git switch master && git merge -s ours stable && git push any time before branching for the 8.8 release. Otherwise, we do nothing and stick with the "merge-with-the-release-branch-when-its-created" strategy.

I don't think we ever followed up on that, and I know I personally was otherwise tied up and couldn't follow the 8.8 release process closely.

It does seem that no one has complained of any strangeness in the GitHub UI. But git describe could arguably be considered UI. It did come up in adjust build stamp for development and snapshots by LiberalArtist · Pull Request #4871 · racket/racket · GitHub (prompted by @benknoble).

@benknoble

Perhaps an interim solution would be to tag the "release cuts" like v8.18-cutoff or something

That does seem like a possible path to better git describe output by default while maintaining the linear history on master. (I don't have a strong opinion myself on how to balance these competing desiderata, though.)

If we did that, I think the tags should point to commits like Post-release version for the v8.18 release · racket/racket@02afeae · GitHub, and I'd suggest a naming convention like post/8.18.0.1. In particular, I'd want the names not to start with v and to be clear to both humans and tools that they are not release versions.