release notes file

[Cy Schubert]

On June 23, 2019 5:36:16 PM PDT, Mark Johnston <markj 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?
>
>Virtually all of the 12.0 release notes are for src/ (there are 4 lines
>for ports/pkg and 1 line for docs, and the latter describes a new man
>page in src).  Why is it important to have a single place for everyone
>to commit their entries?
>
>> 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?
>
>I would guess that many src committers simply won't add release notes
>if
>they have to commit to a second repository and use some unfamiliar
>markup format and worry about validating the file.  There are lots of
>__FreeBSD_version bumps that go undocumented until someone else goes in
>and fills in the missing entries.  A plain-text file in src repo for
>src
>release notes is low-friction and creates only marginally more work for
>RE.  "What's cooking for 13?" can just point to the copy of RELNOTES in
>svnweb.
>
>That said, I personally would try to commit my release notes to a doc
>repo file if one existed.  I've spent a few minutes trying to compile
>the 12.0 notes on my desktop and have not been able to get past,
>"cannot
>parse http://www.FreeBSD.org/XML/share/xml/freebsd-xhtml-release.xsl".
>So, I'm probably not a good person to set up release notes for 13.0.  I
>will help fill in entries for commits since the 12.0 if someone else
>does that setup.
>_______________________________________________
>freebsd-hackers at freebsd.org mailing list
>https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
>To unsubscribe, send any mail to
>"freebsd-hackers-unsubscribe at freebsd.org"

Src and ports should each have their own RELNOTES file.

The only operational concern I have is trimming the file, probably when a branch goes EOL.


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