Re: What's cooking in git.git (Mar 2024, #05; Tue, 19)

[Junio C Hamano <gitster@pobox.com>]

"Brian Lyles" <brianmlyles@gmail.com> writes:

> On Wed, Mar 20, 2024 at 11:11 AM Junio C Hamano <gitster@pobox.com> wrote:
>
>> Very much appreciated.  I wonder if we can have a better workflow to
>> do this, like perhaps contributors write a paragraph in the cover
>> letter with the expectation that it will be used in the What's
>> cooking report (which will become an entry in the Release Notes when
>> the topic gets included in a release)?
>
> I think some more official process could be beneficial. As it is, I'm
> wholly unaware of the current process for creating release notes for
> git. Do the maintainers simply review merged changes and write release
> notes as part of cutting a release?

A few things.  There is only one maintainer.  There are development
community members, who act as contributors and as reviewers.  The
maintainer manages how the 'master' branch and other integration
branches advance, and a part of it is to update the release notes.

Documentation/howto/maintain-git.txt outlines the workflow the
current maintainer has adopted, and it has a brief mention on the
"What's cooking" report.  These days, entries in the the release
notes for each topic merged are mostly copied from "What's cooking"
but currently, as the "howto/maintain-git" document describes,
summarizing and maintaining these topic descriptions is done by the
maintainer.

In the message you responded to, I was wondering if we can
distribute the load even further to have original author of each
topic write the initial draft of the one-paragraph description of
the topic that will go in "What's cooking".  Two obvious downsides
are that having people write about their own work would may make the
result harder to read, as they inevitably are biased by the
importance of their own work ;-), and having many people write
different entries may lose the consistent voice across topics being
described, but the distribution of burden is certainly attractive.

> This way, the
> contributor of a series is responsible for creating the changelog entry
> (or entries) rather than the maintainer, which can help avoid
> inaccuracies from a maintainer with less familiarity trying to
> summarize.

It however cuts both ways.

Trying to coming up with a summary from what I can read from the
discussion and the log messages is a good opportunity to find what
is still unclear in the log messages of the commits in the topic.
Not all contributors can write a good summary of their own work in a
way that are suitable for the audience of the release notes.  Also
you would want to encourage the maintainer to familiarize with the
topics to be able to summarize them, instead of keeping them in the
dark by doing the release notes entries yourself.