On Thu, Sep 11, 2025 at 09:24:01AM -0700, Reinette Chatre wrote:
> About repeating things: As I see it the annoying repeating results from desire to
> follow the "context-problem-solution" changelog script while also ensuring each
> patch stands on its own. With these new features many patches share the same context
> and then copy&paste results. I see how this can be annoying when going through
> the series and I can also see how this is a lazy approach since the context is
> not tailored to each patch. Will work on this.
Thanks. And I know it makes sense to repeat things to introduce the context
but let's try to keep that at minimum and only when absolutely necessary.
> About too much text that explains the obvious: I hear you and will add these criteria
> to how changelogs are measured. I do find the criteria a bit subjective though and expect
> that I will not get this right immediately and appreciate and welcome your feedback until
> I do.
Yeah, that's fine, don't worry. But it is actually very simple: if it is
visible from the diff itself, then there's no need to state it again in text.
That would be waste of text.
Lemme paste my old git archeology example here in the hope it makes things
more clear. :-)
Do not talk about *what* the patch is doing in the commit message - that
should be obvious from the diff itself. Rather, concentrate on the *why*
it needs to be done.
Imagine one fine day you're doing git archeology, you find the place in
the code about which you want to find out why it was changed the way it
is now.
You do git annotate <filename> ... find the line, see the commit id and
you do:
git show <commit id>
You read the commit message and there's just gibberish and nothing's
explaining *why* that change was done. And you start scratching your head,
trying to figure out why. Because the damn commit message is not worth the
electrons used to display it with.
This happens to us maintainers at least once a week.
--
Regards/Gruss,
Boris.
https://people.kernel.org/tglx/notes-about-netiquette
