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

["Brian Lyles" <brianmlyles@gmail.com>]

On Wed, Mar 20, 2024 at 8:36 PM Junio C Hamano <gitster@pobox.com> wrote:

> "Brian Lyles" <brianmlyles@gmail.com> writes:
> 
>> 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.

Got it -- that certainly provides some good context.

> [...] 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.

From looking at the history of "master", it looks like you take batches
of merges and update the patch notes as part of merging each batch in.
Also good to understand.
 
> 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.

So presumably, a contributor that wanted to see the "final form" of the
release notes for their patch would need to keep an eye on "What's
cooking" and/or 'next' and raise any concerns to the list at that point? 

> 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".

I definitely think that it makes sense for the original author to write
*something*.

> [...] 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 ;-)

Yes, this is certainly a possibility. That said, one big advantage of
incorporating this as part of the patch submission (one way or another)
might be that more people will see and have a chance to review the
release notes as part of their normal review of the patch.

> [...] and having many people write
> different entries may lose the consistent voice across topics being
> described, but the distribution of burden is certainly attractive.

It seems that this is not much different from maintaining a consistent
voice across commit messages. Those expectations are well documented,
and commit messages are reviewed thoroughly as part of patch review. I
expect that we could see similar success for the release notes.

>> 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.

I do see the benefit here, and if the maintainer wants to continue
accepting that burden, power to them ;). I certainly would not want
contributor-authored release notes to replace the maintainer being
familiar with ongoing changes.

That said, it would seem that we could have our cake and eat it too --
the maintainer may still choose to familiarize themself with the topics
however they wish, and simply validate the release notes instead of
needing to write them from scratch. Though perhaps in practice, it is
difficult to do so without some additional bias as well.

In any case, for what it's worth: as a contributor, I would certainly be
willing to take on some additional burden as part of submitting a patch
to ensure that my patch is well represented in the release notes. If it
happens to reduce the burden on the maintainer as well, even better!

-- 
Thank you,
Brian Lyles