Re: [boost] New Boost Website: Open to Volunteers!

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