release notes file

[Rodney W. Grimes]

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

I echo your concerns.

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

Very much my position on the issue of a simple text file as
src/RELNOTES, see other reply.

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

Even having you do the simple text in the RELNOTES file is 90% of the
work, formatting, markdown, whatever, lets let the doc experts deal
with that.  This would be a case where we could consistantly delivery
a fair bit of simple text for them to work on, and it would take work
load off RE at .

-- 
Rod Grimes                                                 rgrimes at freebsd.org