# Oddities in branching structure **URL:** \ **Category:** General\ **Tags:** internals\ **Created:** [September 4, 2025, 2:48am UTC](https://racket.discourse.group/t/oddities-in-branching-structure/3930 "2025-09-04T02:48:57Z")\ **Posts on this page:** 1\ **Showing post:** 4
**Author:** ![LiberalArtist](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/liberalartist/32/151_2.png) [@LiberalArtist](https://racket.discourse.group/u/LiberalArtist)\ **Post date:** [September 5, 2025, 6:40am UTC](https://racket.discourse.group/t/oddities-in-branching-structure/3930/4 "2025-09-05T06:40:26Z")
> [@benknoble](#): > > it took me quite a while to connect the dots to [Proposed stable branch discipline](https://racket.discourse.group/t/proposed-stable-branch-discipline/1453) 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: > [@Racket v8.6 Release Thread](https://racket.discourse.group/t/racket-v8-6-release-thread/1091/32): > > 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](https://github.com/racket/racket/commit/424d167500a9c5cb83e3f23217028954f47a69b7) 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](https://github.com/racket/racket/pull/4460). We picked that back up with: > [@Racket v8.7 Release Thread](https://racket.discourse.group/t/racket-v8-7-release-thread/1343/3): > > @jbclements, just wanted to make sure you saw this: [Make `release` a descendant of `stable` by LiberalArtist · Pull Request #4460 · racket/racket · GitHub](https://github.com/racket/racket/pull/4460) > [@Racket v8.7 Release Thread](https://racket.discourse.group/t/racket-v8-7-release-thread/1343/4): > > Yes. Did my response (sent on a plane so who knows) actually get to you? > [@Racket v8.7 Release Thread](https://racket.discourse.group/t/racket-v8-7-release-thread/1343/5): > > Yes, I've just written back. Tl;dr the simple part should be simple, but you were right about: > > > [@Racket v8.6 Release Thread](https://racket.discourse.group/t/racket-v8-6-release-thread/1091/29): > > > > 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: > [@Racket v8.7 Release Thread](https://racket.discourse.group/t/racket-v8-7-release-thread/1343/13): > > > [@Racket v8.7 Release Thread](https://racket.discourse.group/t/racket-v8-7-release-thread/1343/10): > > > > - 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](https://github.com/racket/release-catalog/blob/master/scripts/add-tags.rkt) 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: > > > [@Racket v8.6 Release Thread](https://racket.discourse.group/t/racket-v8-6-release-thread/1091/30): > > > > 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: > [@Racket v8.7 Release Thread](https://racket.discourse.group/t/racket-v8-7-release-thread/1343/13): > > > [@Racket v8.7 Release Thread](https://racket.discourse.group/t/racket-v8-7-release-thread/1343/10): > > > > - 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](https://gist.github.com/LiberalArtist/130452b8086c8007c08d6a0ee552c4f2#file-branches-pdf) @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: > [@Proposed stable branch discipline](https://racket.discourse.group/t/proposed-stable-branch-discipline/1453/3): > > Re: > > > [@Racket v8.7 Release Thread](https://racket.discourse.group/t/racket-v8-7-release-thread/1343/22): > > > > 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: > > > [@Racket v8.7 Release Thread](https://racket.discourse.group/t/racket-v8-7-release-thread/1343/10): > > > > 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](https://github.com/racket/racket/pull/4871#issuecomment-1872426938) (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](https://github.com/racket/racket/commit/02afeae0aaf12065dde4afdb5df3278e23bedf43), and I'd suggest a naming convention like `after/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. --- _[View the full topic](https://racket.discourse.group/t/oddities-in-branching-structure/3930)._