release notes file

[Glen Barber]

On Wed, Jun 26, 2019 at 08:45:15PM -0400, Mark Johnston wrote:
> On Sun, Jun 23, 2019 at 03:18:18PM -0400, 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.
> 
> To be clear, my aim here is to help ensure that new features are
> documented close to when they are committed.  Today, release notes are
> compiled only shortly before a release, which means that re@ has to go
> through all of the new commits looking for relnotes tags and hope that
> they didn't miss anything.  A RELNOTES file helps prevent things from
> falling through the cracks and reduces the amount of work required of
> re at .
> 
> > For example:
> > 
> > Index: RELNOTES
> > ===================================================================
> > --- RELNOTES	(nonexistent)
> > +++ RELNOTES	(working copy)
> > @@ -0,0 +1,8 @@
> > +Release notes for FreeBSD 13.0.
> > +
> > +r349286:
> > +	swapon(8) can now erase a swap device immediately before
> > +	enabling it, similar to newfs(8)'s -E option.  This behaviour
> > +	can be specified by adding -E to swapon(8)'s command-line
> > +	parameters, or by adding the "trimonce" option to a swap
> > +	device's /etc/fstab entry.
> > 
> > What do folks think?
> 
> To summarize what I think are the important points from the discussion
> that ensued:
> 
> - RELNOTES would be useful.  In other words, I didn't see any
>   opposition to the idea.

I did not see opposition either.

> - It's not clear when and how RELNOTES should be truncated.  Since this
>   is really an re@ policy question, it doesn't block RELNOTES from
>   being added to the tree.  So, I will ignore this issue and let them
>   figure it out once we actually come up to the next release and have
>   some experience.

Here is my view of the world in this regard.  Release notes between
X.Y-1 and X.Y should be differences between X.Y-1 and X.Y.  Major
version releases are trickier, because there's the open-ended question
of "against what release do we compare the release notes?"  To be
honest, I still do not have a good metric upon which to base the latter,
but just throwing it at the wall to see what sticks.

> - It's not clear how best to handle MFCs of RELNOTES.  I will propose
>   that we simply not MFC RELNOTES for now: given head's copy of
>   RELNOTES, one can easily determine whether any of the referenced
>   revisions are in a stable branch.

For 12.0 and later, release notes files (the XML files) exist in the doc
tree.  For 11.x and earlier, they exist in src, but since I have been
personally involved in release notes for the past 12 or so releases,
I have never done an MFC from head to stable for the release/doc
directory.  It does indeed cause merge conflicts, and more importantly,
the revision numbers associated with the commit are wrong unless
manually fixed.  My $0.02 USD is to commit to the file on head and
stable branches directly, and *never* do an MFC to the RELNOTES file.
It is, in my experience, just not worth dealing with the conflicts.

> - RELNOTES should be easy to parse.

This is why I am in preference of a plain-text file, wrapped at 80
characters.  I do not necessarily care about nonexistent parsing
capabilities in other software at the moment.

> - RELNOTES is not intended to be presented directly to users; it is a
>   log that can be used to generate user-friendlier documentation.  So,
>   it will not be installed and entries should be in plain text.

Yes.  (See previous comment.)

> - (Not actually discussed, but my own thoughts:) There is some overlap
>   with UPDATING; some things that I would consider release notes are
>   documented there.  As I understand it, the goal of UPDATING is to
>   document changes that may trip up users who build from source: KBI
>   changes, renames, removals, and so on.  RELNOTES is for users of
>   binary FreeBSD releases.  So, there may be some overlap, but in
>   general I think we should avoid using UPDATING to document routine
>   changes like contrib/ updates.
> 

100% agreed.  Furthermore, the RELNOTES file can replace things like
"rNNNNNN: Updated Clang (and friends) to upstream 7.0.1." easily with
"rNNNNNN: Updated Clang (and friends) to upstream 8.0.0."

That, in particular, eliminates some of the relnotes.xml reordering
(based on revision numbers for ease, no other particular reason) when
for example OpenSSL gets bumped mid-cycle.

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/20190627/610c1032/attachment.sig>