first-class merges and cover letters

Sep. 11th, 2025 02:38 am
fanf: (Default)
[personal profile] fanf

https://dotat.at/@/2025-09-11-cover-letter.html

Although it looks really good, I have not yet tried the Jujutsu (jj) version control system, mainly because it's not yet clearly superior to Magit. But I have been following jj discussions with great interest.

One of the things that jj has not yet tackled is how to do better than git refs / branches / tags. As I underestand it, jj currently has something like Mercurial bookmarks, which are more like raw git ref plumbing than a high-level porcelain feature. In particular, jj lacks signed or annotated tags, and it doesn't have branch names that always automatically refer to the tip.

This is clearly a temporary state of affairs because jj is still incomplete and under development and these gaps are going to be filled. But the discussions have led me to think about how git's branches are unsatisfactory, and what could be done to improve them.

branch

One of the huge improvements in git compared to Subversion was git's support for merges. Subversion proudly advertised its support for lightweight branches, but a branch is not very useful if you can't merge it: an un-mergeable branch is not a tool you can use to help with work-in-progress development.

The point of this anecdote is to illustrate that rather than trying to make branches better, we should try to make merges better and branches will get better as a consequence.

Let's consider a few common workflows and how git makes them all unsatisfactory in various ways. Skip to cover letters and previous branch below where I eventually get to the point.

merge

A basic merge workflow is,

  • create a feature branch
  • hack, hack, review, hack, approve
  • merge back to the trunk

The main problem is when it comes to the merge, there may be conflicts due to concurrent work on the trunk.

Git encourages you to resolve conflicts while creating the merge commit, which tends to bypass the normal review process. Git also gives you an ugly useless canned commit message for merges, that hides what you did to resolve the conflicts.

If the feature branch is a linear record of the work then it can be cluttered with commits to address comments from reviewers and to fix mistakes. Some people like an accurate record of the history, but others prefer the repository to contain clean logical changes that will make sense in years to come, keeping the clutter in the code review system.

rebase

A rebase-oriented workflow deals with the problems of the merge workflow but introduces new problems.

Primarily, rebasing is intended to produce a tidy logical commit history. And when a feature branch is rebased onto the trunk before it is merged, a simple fast-forward check makes it trivial to verify that the merge will be clean (whether it uses separate merge commit or directly fast-forwards the trunk).

However, it's hard to compare the state of the feature branch before and after the rebase. The current and previous tips of the branch (amongst other clutter) are recorded in the reflog of the person who did the rebase, but they can't share their reflog. A force-push erases the previous branch from the server.

Git forges sometimes make it possible to compare a branch before and after a rebase, but it's usually very inconvenient, which makes it hard to see if review comments have been addressed. And a reviewer can't fetch past versions of the branch from the server to review them locally.

You can mitigate these problems by adding commits in --autosquash format, and delay rebasing until just before merge. However that reintroduces the problem of merge conflicts: if the autosquash doesn't apply cleanly the branch should have another round of review to make sure the conflicts were resolved OK.

squash

When the trunk consists of a sequence of merge commits, the --first-parent log is very uninformative.

A common way to make the history of the trunk more informative, and deal with the problems of cluttered feature branches and poor rebase support, is to squash the feature branch into a single commit on the trunk instead of mergeing.

This encourages merge requests to be roughly the size of one commit, which is arguably a good thing. However, it can be uncomfortably confining for larger features, or cause extra busy-work co-ordinating changes across multiple merge requests.

And squashed feature branches have the same merge conflict problem as rebase --autosquash.

fork

Feature branches can't always be short-lived. In the past I have maintained local hacks that were used in production but were not (not yet?) suitable to submit upstream.

I have tried keeping a stack of these local patches on a git branch that gets rebased onto each upstream release. With this setup the problem of reviewing successive versions of a merge request becomes the bigger problem of keeping track of how the stack of patches evolved over longer periods of time.

cover letters

Cover letters are common in the email patch workflow that predates git, and they are supported by git format-patch. Github and other forges have a webby version of the cover letter: the message that starts off a pull request or merge request.

In git, cover letters are second-class citizens: they aren't stored in the repository. But many of the problems I outlined above have neat solutions if cover letters become first-class citizens, with a Jujutsu twist.

  • A first-class cover letter starts off as a prototype for a merge request, and becomes the eventual merge commit.

    Instead of unhelpful auto-generated merge commits, you get helpful and informative messages. No extra work is needed since we're already writing cover letters.

    Good merge commit messages make good --first-parent logs.

  • The cover letter subject line works as a branch name. No more need to invent filename-compatible branch names!

    Jujutsu doesn't make you name branches, giving them random names instead. It shows the subject line of the topmost commit as a reminder of what the branch is for. If there's an explicit cover letter the subject line will be a better summary of the branch as a whole.

    I often find the last commit on a branch is some post-feature cleanup, and that kind of commit has a subject line that is never a good summary of its feature branch.

  • As a prototype for the merge commit, the cover letter can contain the resolution of all the merge conflicts in a way that can be shared and reviewed.

    In Jujutsu, where conflicts are first class, the cover letter commit can contain unresolved conflicts: you don't have to clean them up when creating the merge, you can leave that job until later.

    If you can share a prototype of your merge commit, then it becomes possible for your collaborators to review any merge conflicts and how you resolved them.

To distinguish a cover letter from a merge commit object, a cover letter object has a "target" header which is a special kind of parent header. A cover letter also has a normal parent commit header that refers to earlier commits in the feature branch. The target is what will become the first parent of the eventual merge commit.

previous branch

The other ingredient is to add a "previous branch" header, another special kind of parent commit header. The previous branch header refers to an older version of the cover letter and, transitively, an older version of the whole feature branch.

Typically the previous branch header will match the last shared version of the branch, i.e. the commit hash of the server's copy of the feature branch.

The previous branch header isn't changed during normal work on the feature branch. As the branch is revised and rebased, the commit hash of the cover letter will change fairly frequently. These changes are recorded in git's reflog or jj's oplog, but not in the "previous branch" chain.

You can use the previous branch chain to examine diffs between versions of the feature branch as a whole. If commits have Gerrit-style or jj-style change-IDs then it's fairly easy to find and compare previous versions of an individual commit.

The previous branch header supports interdiff code review, or allows you to retain past iterations of a patch series.

workflow

Here are some sketchy notes on how these features might work in practice.

One way to use cover letters is jj-style, where it's convenient to edit commits that aren't at the tip of a branch, and easy to reshuffle commits so that a branch has a deliberate narrative.

  • When you create a new feature branch, it starts off as an empty cover letter with both target and parent pointing at the same commit.

  • Alternatively, you might start a branch ad hoc, and later cap it with a cover letter.

  • If this is a small change and rebase + fast-forward is allowed, you can edit the "cover letter" to contain the whole change.

  • Otherwise, you can hack on the branch any which way. Shuffle the commits that should be part of the merge request so that they occur before the cover letter, and edit the cover letter to summarize the preceding commits.

  • When you first push the branch, there's (still) no need to give it a name: the server can see that this is (probably) going to be a new merge request because the top commit has a target branch and its change-ID doesn't match an existing merge request.

  • Also when you push, your client automatically creates a new instance of your cover letter, adding a "previous branch" header to indicate that the old version was shared. The commits on the branch that were pushed are now immutable; rebases and edits affect the new version of the branch.

  • During review there will typically be multiple iterations of the branch to address feedback. The chain of previous branch headers allows reviewers to see how commits were changed to address feedback, interdiff style.

  • The branch can be merged when the target header matches the current trunk and there are no conflicts left to resolve.

When the time comes to merge the branch, there are several options:

  • For a merge workflow, the cover letter is used to make a new commit on the trunk, changing the target header into the first parent commit, and dropping the previous branch header.

  • Or, if you like to preserve more history, the previous branch chain can be retained.

  • Or you can drop the cover letter and fast foward the branch on to the trunk.

  • Or you can squash the branch on to the trunk, using the cover letter as the commit message.

questions

This is a fairly rough idea: I'm sure that some of the details won't work in practice without a lot of careful work on compatibility and deployability.

  • Do the new commit headers ("target" and "previous branch") need to be headers?

  • What are the compatibility issues with adding new headers that refer to other commits?

  • How would a server handle a push of an unnamed branch? How could someone else pull a copy of it?

  • How feasible is it to use cover letter subject lines instead of branch names?

  • The previous branch header is doing a similar job to a remote tracking branch. Is there an opportunity to simplify how we keep a local cache of the server state?

Despite all that, I think something along these lines could make branches / reviews / reworks / merges less awkward. How you merge should me a matter of your project's preferred style, without interference from technical limitations that force you to trade off one annoyance against another.

There remains a non-technical limitation: I have assumed that contributors are comfortable enough with version control to use a history-editing workflow effectively. I've lost all perspective on how hard this is for a newbie to learn; I expect (or hope?) jj makes it much easier than git rebase.

[syndicated profile] dinosaur_comics_feed
archive - contact - sexy exciting merchandise - search - about
September 10th, 2025next

September 10th, 2025: Don't worry - I have been to SEVERAL parties so I know what I'm talking about!!

So last week T-Rex suggested a new alphabet replacement, and I got an email from Michael L, who wrote:

I took the liberty of finding you the first 26 Garfield comics with no text in them (barring bookkeeping text like dates and signatures ofc) so you don't have to worry about recursively putting Garfield comics inside Garfield comics in order to make them parseable.

I thought this was both amazing AND PRACTICAL, and so with permission I now share this list here with you!!

  • 1978 (Strip #68): The tail ratchet.
  • 1978 (Strip #78): Preparing for the bath.
  • 1978 (Strip #79): The dandelion drying.
  • 1980 (Strip #4): The pin-up posters.
  • 1980 (Strip #48): The tail adjustment. (Sunday)
  • 1980 (Strip #172): Odie ties himself in a knot.
  • 1980 (Strip #180): The door/window prank. (Sunday)
  • 1980 (Strip #198): Sucking the teddy bear's paw.
  • 1980 (Strip #332): Teeth grow into the table.
  • 1981 (Strip #125): The instant rainstorm.
  • 1981 (Strip #147): Fur blown back in the car.
  • 1981 (Strip #175): Paws stuck in the collar.
  • 1981 (Strip #308): Stretching Odie's ear.
  • 1981 (Strip #313): Stuck in the kitty sweater.
  • 1981 (Strip #328): Neck stretches in the window shade.
  • 1982 (Strip #32): Juggling apple cores.
  • 1982 (Strip #39): Slingshot stuck on face.
  • 1982 (Strip #62): Ambushing the hat ornament.
  • 1982 (Strip #64): Devouring the popcorn.
  • 1982 (Strip #73): Swing breaks on head.
  • 1982 (Strip #150): Fishing hook snags tail.
  • 1982 (Strip #151): Garfield becomes Odie's tail.
  • 1982 (Strip #152): Sandwich fillings squish out.
  • 1982 (Strip #167): Cat door hits him in the rear.
  • 1982 (Strip #197): Scale arrow peaks + Garfield's reaction.
  • 1982 (Strip #244): Napkin cape leaves him dangling.

– Ryan

I reactivated Netflix tonight

Sep. 10th, 2025 12:43 am
rmc28: Rachel in hockey gear on the frozen fen at Upware, near Cambridge (Default)
[personal profile] rmc28

... so I could watch Kpop Demon Hunters, after half my friends mentioned it, and my child told me it was good, and the songs kept turning up on my instagram feed, and I listened to the soundtrack yesterday.

Anyway, it was a great deal of fun, the music is so catchy, the film absolutely leans into its premise, and I thoroughly enjoyed the experience. I'm not great at watching TV at all, and especially not by myself, but I'm glad I did. (I might put it on again, maybe the singalong version, at some point.)

I watched approx 2/3 of it between skating lesson and uni hockey practice and the other 1/3 after getting home. I'd just turned it off to get changed, when in walked the students with the speaker playing the soundtrack (and one of the songs, Golden, lived on repeat in my head throughout practice).

BATS

Sep. 9th, 2025 09:56 pm
kaberett: Trans symbol with Swiss Army knife tools at other positions around the central circle. (Default)
[personal profile] kaberett

Between one thing and another we wound up having a semi-impromptu mini-break in Chester, including a few hours at Chester Zoo.

... where we went into the bats enclosure and were transfixed for about an hour, basically from the moment we walked in until chucking-out time.

It's a big dark room, artificially crepuscular, with lots of trees (dead) for roosts, and somewhere in the vicinity of 350 bats (Seba's short-tailed and Rodrigues fruit bats). THEY WILL COME SO CLOSE TO YOU. THEY WILL COME SO CLOSE TO YOU. They were flying well within a foot of our faces. You could FEEL THE WIND FROM THEIR WINGBEATS.

And A was greatly honoured by one LANDING ON THEIR TROUSERS.

There were many other Excellent Creatures -- the Humboldt penguins in particular were very excited by the rain (so much porpoising), and the giant otters were indeed giant, and there was an enormous dragonfly, and the flamingos went from almost entirely asleep (including one baby that had not yet got the hang of the whole one-leg trick) to YELLING INCESSANTLY after being buzzed by the scarlet ibis.

Extremely good afternoon out, 13/10, would recommend.

[syndicated profile] dorktower_feed

Posted by John Kovalic

For the thirteenth year, I’m taking to a bicycle, to help raise money to help local farmers get fresh-food to local low-income and elderly households.

This year will be different, however. IF we can hit the $20,000 goal:

(a) I will cycle with the Duck of Doom on my helmet, but more importantly

(b) That will bring the grand total of all Insane Charity Bike Rides (2011-2025) to A QUARTER OF A MILLION DOLLARS!

A few things to note:

  • The original Munchkin card art at the $375 and above levels will be from a MAJOR upcoming Munchkin release. How major? I can’t say what it its, but it will be announced at Gamehole Con in October, and it should blow your socks off! You won’t want to miss it!
  • I’ve added Sponsorship levels, so companies can pick up advertising at DorkTower.com that is 100% a charitable deduction, tax-wise. These may be added to any level.
  • The 2024 swag went out later than I had hoped. This was entirely on me. I shall endeavor this year to have all swag sent off by US Thanksgiving, 2025.
  • Due to a terribly busy summer, this is the latest I’ve ever launched an Insane Charity Bike Ride campaign, so I’m kind of worried about hitting the $20,000 goal. But I have hope…

SUPPORT LEVELS AND REWARDS

ANY donation – The 2025 Coloring Book PDF . Look, even simply getting the word out helps, but nothing beats cash. I realize money is tight these days all round, but any amount helps, no matter how small. Donate, and you will get a PDF of the brand-new coloring book (hopefully celebrating the $250,000 landmark).

$35The 2025 Munchkin Charity Postcard and the 2025 Coloring Book PDF.

$75 The 2025 Army of Dorkness Sergeant Button, the 2025 Postcard the 2025 Coloring Book PDF

$125Kovalic’s Munchkin Miscellany – I’ve a few copies of this comic book left from the Munchkin BIG BOX Kickstarter, and Steve Jackson Games has graciously allowed me to use these for charity purposes.

There’s lots of nifty stories and favorite bits of art in this, and it’s a ton of fun! Also, you get the Button, 2025 Postcard, Munchkin Miscellany and the 2025 Coloring Book PDF (14 of 15 remaining)

$200 All 12 prior Insane Charity Bike Ride Postcards, Munchkin Miscellany, the 2025 Button, 2025 Postcard, and the 2025 Coloring Book PDF (8 of 10 remaining)

$300The 2025 Gamehole Con plushie, Karlos the Kobold, Munchkin Miscellany, Button, 2025 Postcard, the 2025 Coloring Book PDF (20 of 20 remaining)

$375Original Munchkin Art!!! As always, I don’t sell original Munchkin art. This is the only way you can obtain a piece, and the upcoming release this year’s art will be selected from will be HUGE. Plus, Munchkin Miscellany, the 2025 Button, all 12 prior Postcards, 2025 Postcard, the 2025 Coloring Book PDF (16 of 20 remaining)

$600 – Be among the first to read THE DORK WEB, the new Dork Tower collection, along with a DORK WEB T-shirt and a Gilly the Perky Goth plushie along with a limited signed and sketched-in edition of the book itself, when it’s released in early 2026! Plus All Prior Postcards, Original Munchkin Art, Kobold plushie, Munchkin Miscellany, Button, Postcard the 2025 Coloring Book PDF (10 of 10 remaining)

$1000Appear in a Dork Tower Comic! You, your frtiend, your family, or even a pet will appear in a Dork Tower strip! We can talk about how best to fit you or your loved one into a strip. You also get Original Art, a pre-publication copy of The Dork Web PDF, T-shirt, Signed and Sketched limited edition copy of the Dork Web when published, Gilly the Perky Goth Plushie, All Prior Postcards, Original Munchkin Art, Kobold, Munchkin Miscellany, Button, Postcard the 2025 Coloring Book PDF (2 of 2 remaining)

$2,000Become an Official Munchkin Card! You, a friend, your family, or even a pet will become an official Munchkin card! You also get 100 printed cards and the card’s original art, along with a pre-publication copy of The Dork Web PDF, T-shirt, Signed and Sketched limited edition copy of the Dork Web when published, Gilly the Perky Goth Plushie, All Prior Postcards, Original Munchkin Art, Kobold, Munchkin Miscellany, Button, Postcard the 2025 Coloring Book PDF (2 of 2 remaining)

SPONSORSHIP LEVEL 1Add $1,250 to any level for six months of ads on DorkTower.com. The ads may be changed up to four times and may include Dork Tower characters. (4 of 4 remaining)

SPONSORSHIP LEVEL 2Add $2,000 to any level for a full year of ads on DorkTower.com. The ads may be changed up to eight times and may include Dork Tower characters. (2 of 2 remaining)

PLEASE NOTE, there may be an added cost for shipping the physical rewards outside of the United States, depending on the whims of the current US administration. We apologize deeply for this, and will contact supporters as the time approaches.

STRETCH GOALS

Hitting $5,000 – A sticker commemorating the 13th Insane Charity Bike Ride campaign will be included with all physical orders.

Hitting $10,000 – I’ll ride with the Steve Jackson Games Tentacles of Doom again!

Hitting $15,000 – A unique Munchkin card commemorating the 13th Insane Charity Bike Ride campaign will be included with all physical orders.

Hitting $20,000 – THE DUCK! THE DUCK! THE DUCK! I’ll ride with the Steve Jackson Games Duck of Doom on my helmet again!

Hitting $25,000 – (To be announced. Mmmmmmmmaybe the second duck? Hmmmmmmmm?)

I’m TOTALLY nervous about making the goal this year, but let’s help local farmers help local families, and do some more good for the world!

  • John

 

[syndicated profile] dinosaur_comics_feed
archive - contact - sexy exciting merchandise - search - about
September 8th, 2025next

September 8th, 2025: The bold return of Tiny Batman Head! Only now I've written for DC so uh it's even MORE important that we all just BE COOL ABOUT THIS

– Ryan

vital functions

Sep. 7th, 2025 10:50 pm
kaberett: Trans symbol with Swiss Army knife tools at other positions around the central circle. (Default)
[personal profile] kaberett

Reading. Lake of Souls, Ann Leckie: finished the Radch stories; on to The World Of The Raven Tower!

The Painful Truth, Monty Lyman: in progress; not yet Cross with it but also not yet Impressed by it.

More Dreamwidth catchup.

Listening. More Hidden Almanac!

Eating. SO many tomatoes.

Exploring. Poked around Preston a very little!

Growing. ... SO many tomatoes. More watering system established at plot (so hopefully all the peppers will still be alive and well upon my return). Sowed some probably-past-it seeds.

Observing. A saw a deer on the drive up to Preston! A proper big one with antlers and all! We were very impressed.

Also the local owl Yell.

squirmelia: (Default)
[personal profile] squirmelia
A sign on the gate at Gabriel’s Wharf warned that the foreshore was unsafe and to keep away, but I'd read elsewhere these weren't official signs and no-one knew what was more unsafe than usual about it.

I walked through the gate anyway and headed onwards, waiting for the tide low enough to get to the patch of foreshore outside the National Theatre.

While I was waiting I found what I thought was a coin, but things are deceptive on the foreshore and when I got it home, it had transformed into something else, although I don't know what.

A pair of tourists sat on the steps by the locked gate, chatting loudly.

In front of me on the waves were seagulls bobbing and I could hear the clink clink sound of boats, and the clatter of the waves against the pebbles. I felt happy to be there, by this river.

I found some large pieces of what were once pots of some kind. One with the letters, “ING” which was probably another Maling marmalade jar. One with “London” and some other indecipherable words, and one which probably once said “pottery” and “Derby”. That may have been for ink.

I found a lot with letters on! Numbers also: a thing that has “55 14” on it. A letter ‘T’, on a piece that was reddish with a cross. An ‘E. Letters that probably once spelt ‘England’.

These are all in the first picture:

Mudlarking finds - 42.1

In the second picture:

A cat bread sticker, looking particularly strange.

A wooden thing. Is it something carved and used by humans or just a bit of tree root that ended up in the Thames?

A domino. But where are the rest of the dominoes?

A blue pottery sherd with what looks like ‘TS’ on it.

A pottery sherd that looks like it says "fex" on it, but that seems unlikely.

The metal brown circle.

A tip of a pipe, and a decent bit of pipe and bowl.

Mudlarking finds - 42.2

In the third picture:

An Aynsley China sherd.

A little button.

Some nice colourful pieces of glass.

A shard of glass that says “Pepsi” on it.

Mudlarking finds - 42.3

The sun was getting low in the sky and the light was fading as I walked back across to the beach by Gabriel’s Wharf, before the tide came back in.

(You need a permit to mudlark or search on the Thames foreshore.)

I Saw The TV Glow

Sep. 6th, 2025 07:43 pm
emperor: (Default)
[personal profile] emperor
This is the last of this year's Hugo Award shortlist for dramatic presentation long form. It's very strange. Owen and Maddy are disaffected teenagers who bond over their obsession with The Pink Opaque. How much of it is warping their perception of reality or actually warping reality is left unanswered; the whole film proceeds at a very slow pace, and that plus the occasional breaking of the fourth wall give it a dreamlike or nightmareish quality. I think it is talking about fandom, queerness, and gender, but I didn't really get it. And the end was a damp squib.

I didn't vote in this category, but if I had I think I would have ranked Flow first; it came second behind Dune.
[syndicated profile] dorktower_feed

Posted by John Kovalic

This or any DORK TOWER strip is now available as a signed, high-quality print, from just $25!  CLICK HERE to find out more!

HEY! Want to help keep DORK TOWER going? Then consider joining the DORK TOWER Patreon and ENLIST IN THE ARMY OF DORKNESS TODAY! (We have COOKIES!) (And SWAG!) (And GRATITUDE!)

 

kaberett: Trans symbol with Swiss Army knife tools at other positions around the central circle. (Default)
[personal profile] kaberett

Or at least "the other line I meant to highlight from the Wikipedia article":

There is increasing evidence that the smooth muscle that lines the airways becomes progressively more sensitive to changes that occur as a result of injury to the airways from dehydration.

I had only taken 700ml of water with me; I'd blithely assumed I'd be able to top up at the café and then had Too Much Social Anxiety to ask or even check whether they had a jug out, because that's a thing my brain is definitely Doing at the moment. ... and then on the way back I was desperately thirsty and stole most of A's water, and I am just personally finding it Very Interesting that the thing my body wanted me to do most was More Fluids.

[syndicated profile] dinosaur_comics_feed
archive - contact - sexy exciting merchandise - search - about
September 5th, 2025next

September 5th, 2025: I want it on record, specifically because he does not, that my friend PATRICK WISKING is the inventor of the chocochop! I am merely its #1 fan and salesperson!!

– Ryan

Profile

ghoti_mhic_uait: (Default)
ghoti_mhic_uait

November 2024

S M T W T F S
     12
3456789
10111213141516
17181920212223
24252627282930

Most Popular Tags

Style Credit

Expand Cut Tags

No cut tags
Page generated Sep. 11th, 2025 08:10 am
Powered by Dreamwidth Studios