On Wed, 30 Jul 2025 at 12:24, Paul E. McKenney <paul...@kernel.org> wrote:
>
> As it happens, I will be sending the pull request for the v6.18 merge
> window, so I will stop doing my usual octopus merges (hey, they *were*
> cool!) and instead merge each branch separately, with each merge's commit
> log giving a synopsis of the commits in the branch being merged.
Note that octopus merges aren't a no-no per se. Sometimes they make
perfect sense, particularly if there's a handful of really trivial
branches with just a commit or two each.
Then an octopus merge can be a really convenient way to avoid having
as many merges as you have "real" commits.
So don't take my comment as a "never use octopus merges".
Take it more as "octopus merges have some downsides, and making _any_
merge without an explanation for it in the commit message is bad".
The main downside of octopus merges really is just bisectability:
because even if the problem doesn't end up being the merge itself, an
octopus merge can make it fundamentally hard to do the "cut the
history in two roughly equal points for testing".
But again, that's not a problem if you have just a fairly small
handful of purely trivial commits.
So people just need to balance the "octopus merges are cool, and can
avoid pointless repeated silly small merges" with "octopus merges can
make for bisectability issues and should be avoided for anything even
halfway comples".
(Also, try *very* hard to avoid octopus merges when any conflicts
exist - even trivial ones. Octopus merges with conflict resolution
take "that's hard to follow" to a whole other level, to the point
where you really shouldn't even try).
> If you have a best-practice series of merges example in mind, could you
> please point me at it?
It's hard to give a good "typical" example, because I don't think
"typical" exists.
Sometimes a simple one-line merge message just stating "Misc fixes for
subsystem Xyz" really might be the "proper" merge message.
Because maybe that branch really had all just tiny uninteresting
fixes, and git shortlog entirely describes it all to the point that
writing anything more would just be wasting everybody's time.
Honestly, the merge messages you guys send me for *my* RCU merge are
fine - the only thing I ask for is that instead of describing the
branches with an esoteric branch name, you write them out for humans.
So having the header read "Improvements expedited RCU grace periods"
or something is just _soo_ much more understandable than
"rcu-exp.23.07.2025", wouldn't you agree?
As to the merge messages for *your* own merges, where you just put
several branches together in order to send the result to me: knowing
that there will be a more complete message in the upstream merge, I
think the main issue is to think about people who hit that merge
because they have some issue.
So again, it might be because somebody ends up hitting that merge
during bisection, or has some other reason why they are looking at
that merge in particular, rather than the "bigger picture" upstream
merge.
In other words, please write merge messages with the intended audience
in mind. They don't necessarily need to be the same kind of
full-fledged explanation that I want to explain why I'm merging (and
for people who follow the development process: people most definitely
look at the pull requests that come upstream, and it's informative to
not just me, but you find tech press etc looking at them too).
But you should at a minimum think about "what if somebody hits this
during a bisection". Give those random developers a clue about what is
going on. Don't just make it be that "Merge branch XYZ", because that
tells _outsiders_ so little.
Does that make sense as an answer?
Anyway, I'm happy to say that if you are looking for _examples_ of
merges, we have tons of them. I'm proud of the fact that I think
kernel commit messages in general are very good, and when I compare
them to other projects I feel like we tend to do a stellar job. And
I'm not just patting myself on the back, we have tons of good
examples.
So you can do a
git log --merges
in general, and while you'll find some that just list branches, I
think most of them tend to be very good these days. Look at the
networking and bpf merges, for example (so typically Jakub and
Alexei). Or the SoC merges (Arnd), or the VFS merges (Christian
Brauner).
Or really most of them. I started looking for more names (the ones I
mentioned were people I already knew wrote good merge messages), and
really my reaction was that "most of them are great".
Good on us.
Linus
