release notes file

[Mark Johnston]

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.
- 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.
- 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.
- RELNOTES should be easy to parse.
- 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.
- (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.

I put a proposed initial version here:
https://reviews.freebsd.org/D20762