Re: New Boost Website: Open to Volunteers!

From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2022-04-16 22:10:08

On 4/17/22 00:56, James E. King III via Boost wrote:
> On Sat, Apr 16, 2022 at 5:49 PM Peter Dimov via Boost
> <boost_at_[hidden]> wrote:
>>
>> Vinnie Falco wrote:
>>> We are adding a database, and this kind of feature will be possible in theory.
>>> But, in order to ensure that we actually get this thing done we are limiting the
>>> scope of new features for the initial release. We aren't touching the
>>> documentation and we are striving to make few to no changes in how the
>>> release notes are published.
>>
>> Fixing the way the release notes are published would be pretty useful.
>>
>> We could, e.g. have meta/changelog.json in each library that holds the
>> per-library changes, and generate the release notes from that.
>>
> 
> 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.

Generating release notes from commit messages has one advantage - it's
cheap and almost automatic. But the result is not very good. I prefer to
write release notes explicitly, in a separate document. I'm not in favor
of the specific format of JSON as it is not a documentation format and
does not support features that are often used in documentation and
release notes, such as links, code/preformatted text, bold/italic,
numbered and unnumbered lists and so on.

We probably won't agree on a single common format of such release notes
document, so while I think the idea is good in theory, I don't see how
it can be implemented in practice.