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

On Wed, Mar 20, 2024 at 11:11 AM Junio C Hamano <gitster@pobox.com> wrote:

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 strategy that I have seen work well is for any commit making a notable change (one that should appear in the release notes) to include an entry in a CHANGELOG.NEXT.md file. When cutting a release, the maintainers would move the contents of that CHANGELOG.NEXT.md file into a new section in the standard CHANGELOG.md for the release. 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.

This has the benefit of anyone being able to easily see notable upcoming changes at any point in a release by simply looking to that CHANGELOG.NEXT.md file, rather than needing to review all of the commits added since the previous release.

Of course it does not need to be markdown, that's simply the template [1] that I"m familiar with.

[1]: https://keepachangelog.com/en/1.1.0/

Using my own series as an example, that CHANGELOG.NEXT.md might look like:

    # Unreleased changelog entries
    
    This file contains changelog entries for the next release. Maintainers will move
    these entries to CHANGELOG.md as part of cutting each release.
    
    ## Added
	- git-rebase now supports a `--empty=stop` option for consistency with
	  git-am's similar `--empty` option.
	- git-cherry-pick now supports a `--empty` option to allow more robust
	  control over what happens to redundant commits.
    
    ## Changed
	- git-cherry-pick will now error out if `--keep-redundant-commits`
	  is specified alongside `--continue`, `--skip`, `--abort`, or
	  `--quit`.
    
    ## Deprecated
	- git-rebase's `--empty=ask` has been deprecated in favor of
	  `--empty=stop`, which has the exact same behavior.
	- git-cherry-pick's `--keep-redundant-commits` has been deprecated in
	  favor of `--empty=keep`, which has the exact same behavior.
    
    ## Removed
    
    ## Fixed
	- Documentation for git-rebase's `--empty` now correctly indicates
	  the default behavior when `--exec` or `--interactive` are
	  specified.
	- git-cherry-pick will no longer error out if `--allow-empty` is used
	  while on an unborn branch.
    
    ## Security

We would of course have to decide how detailed these ought to be and what changes do and do not warrant an entry, but presumably we already have to do that as part of the current process for creating each release' notes. So long as we document those expectations, it seems like a reasonable thing to ask of contributors.

An additional benefit here is that the release notes themselves are reviewed as part of the normal patch review process, allowing reviewers to suggest edits to them alongside their code review.

The one minor headache with this process that I am aware of is that applying multiple patches that all touch that one file does lead to some conflicts. For example:

    # Added
	- Some cool new feature!
	<<<<<<< HEAD
	- A different cool new feature!
	=======
	- A third new feature!
	>>>>>>> 9b423104cd (Introduce an awesome feature)

    # Changed

In practice, the rigid structure of adding entries to the end of the list and the blank lines between sections seems to result in these usually (always?) being trivially resolved by simply accepting both sides of the conflict. That said, in the context in which I've seen this, it's been in a forge where each contributor must address this before their pull request is accepted. It may cause more annoyance for your process of accepting changes into your tree -- I'm not sure.

This is simply one idea, of course. I realize that it may not be feasible for this project, but if not then perhaps it may inspire someone else to come up with a better approach.

What are your thoughts?