release notes file

[Warner Losh]

On Mon, Jun 24, 2019 at 9:44 AM Cy Schubert <Cy.Schubert at cschubert.com>
wrote:

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

I'd add truncating the file on -current to the list of things we do when we
branch. then we can MFC RELNOTES as we MFC the features they describe.

Warner