release notes file

[Glen Barber]

On Sun, Jun 23, 2019 at 11:23:57PM +0000, Bjoern A. Zeeb wrote:
> On 23 Jun 2019, at 19:18, Mark Johnston wrote:
> 
> Hi,
> 
> > Today we add a Relnotes tag to commits that warrant a release note.
> > My impression is that it doesn't work so well: if a committer forgets
> > or doesn't know to add one there's no way to amend the commit message
> > (same for MFCs), and a commit message isn't a convenient place to write
> > the text of a release note.  I would like to propose adding a top-level
> > RELNOTES file instead, which like UPDATING would document notes for
> > specific commits.  It would be truncated every time the head branch is
> > forked, and changes to it would be MFCed.  This fixes the
> > above-mentioned problems and would hopefully reduce the amount of time
> > needed by re@ to compile release notes.
> 
> Hooray.  Can we put that file into the doc repo, so that the ports people,
> and the docs people, and all other kinds of hats can put things in there as
> well?
> 
> Oh, the release notes go into the doc repo anyway.  Can we just put them in
> the right place and just fill them from a skeleton where they should be and
> naturally grow the document (feel free to use a different markup language
> once doc is ready for that).
> 
> Oh, with that release notes are written automatically and you are still
> responsible for that your stuff is in there.  And the release notes only
> need an editing pass in the end?
> 
> And the wiki pages like “What’s cooking for 13?” or similar could just
> vanish as we’d have these updated at least every 10 minutes automatically ..
> on our web server under /releases/ where they belong ..
> 
> How amazing would that be?

Very.

But, I have one non-important nit -- the file in question does not need
to be formatted for the documentation language of the day.  In other
words, I do not see this file as a "copy/paste from here to there and be
done with it" sort of thing; i.e., grammar nits, clarifications that
stray from the original commit log (or commit log intent), etc.

When re@ requests clarification on commits or prods committers for
things that may not have otherwise made it into the release notes, it
isn't sent as a "please send us the properly-formatted XML entry" or
some such thing, so personally, I am perfectly fine with a 80-character
line-length raw plain-text entry.

Just my $0.02 USD.

Glen

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-hackers/attachments/20190623/92abbf1b/attachment.sig>