release notes file

[Cy Schubert]

On June 23, 2019 4:48:45 PM PDT, Glen Barber <gjb at freebsd.org> wrote:
>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

I disagree. It should be a .md file to display properly on github. 


-- 
Pardon the typos and autocorrect, small keyboard in use.
Cheers,
Cy Schubert <Cy.Schubert at cschubert.com>
FreeBSD UNIX: <cy at FreeBSD.org> Web: http://www.FreeBSD.org

	The need of the many outweighs the greed of the few.