Re: New Boost Website: Open to Volunteers!

From: Gavin Lambert (boost_at_[hidden])
Date: 2022-04-19 04:20:42

On 17/04/2022 10:10, Andrey Semashev wrote:
> On 4/17/22 00:56, James E. King III wrote:
>> I have to disagree with that.  GitHub provides us with labels, and
>> people should be using reasonable check-in comments.  Instead of
>> having a single collision file like changelog (I have seen this on
>> django-simple-history and it isn't pretty) it would be much better
>> to have a label for a commit that should be included in the
>> release notes and pull the first line of that commit into the
>> release notes with a link to the pull request that it was
>> associated with.  This would be more automated and cause far less
>> commit collisions.  Using a label like `release-note-worthy` to
>> faciliate this would also allow a project maintainer to decide what
>> is worthy by  modifying the labels.
> 
> I have experience with generating release notes from commit messages and
> that doesn't work well in practice. Often, what you want to write in the
> commit message (which is aimed at library maintainers) is very different
> from what you want to write in release notes (which is aimed at library
> users). When you try to combine that the result is not the best for
> either target audience. Plus, you'll have a problem with grouping an
> ordering the release notes, if you want something better than
> chronological order.

+1 for not generating release notes from commit messages.

GitHub does have its own concept of creating releases and release notes 
that are *associated* with a commit while not actually being part of it 
-- which means that they can be edited.  Though one caveat is that it's 
difficult to edit them ahead of time.

Perhaps this could be used -- as part of the release process, GH's API 
is used to generate a release (linked to the commit that's actually in 
the release, with some initial default content that's either 
autogenerated from commit messages or reads some changelog file that's 
part of the repository).  The library maintainer can edit this after the 
fact if they need to.  The website displays the composite of the release 
notes from the various library releases (as edited).

One downside is that the composite release notes would either need to be 
dynamically generated or would need to otherwise detect a change to 
already-published release notes to rebuild.  I'm not sure how easy that 
will be to monitor.

As a bonus, having the GH release means that the source code as of that 
release is downloadable directly from GH, which could simplify modular 
building (and perhaps trend towards getting rid of the monolithic 
download entirely?  Although that still has its uses).