release notes file

[Mark Johnston]

On Sun, Jun 23, 2019 at 08:19:43PM +0000, Glen Barber wrote:
> On Sun, Jun 23, 2019 at 02:01:31PM -0600, Warner Losh wrote:
> > On Sun, Jun 23, 2019 at 1:56 PM Glen Barber <gjb at freebsd.org> wrote:
> > 
> > > FWIW, I don’t think “either/or” is necessarily the best approach; meaning
> > > I would like to still keep the tag in the default template.
> > >
> > 
> > A while ago, I proposed a protocol that we'd only have the RELNOTES file.
> > 
> > The other part of the protocol was to remove it from RELNOTES once it was
> > added to the release notes. This way, we can have multiple people working
> > on the release notes should we be so fortunate to have those resources in
> > the future. It's minorly racy, but not terrible. This way, release notes
> > text could also be written by the committer and tweaked by whomever
> > compiles the release notes.
> > 
> > However, I'm cool with having it in the commit message + template since
> > it's better to have a heads up you need to write something than not. The
> > understanding would be a RelNotes: yes would mean that someone else would
> > write the notes and if you wanted to have more control over what went out,
> > you'd use RELNOTES.
> > 
> > Glen, do you think that's a workable protocol?
> > 
> 
> It's kind of difficult for me to put the words together that effectively
> conveys what I'm thinking or where my mindset is here, but I'll try.
> 
> I am in full support of a RELNOTES file, but I think that should be
> supplementary to the 'Relnotes: yes' (or other variations of a non-empty
> tag).
> 
> I am conflicted on removing entries from a RELNOTES file once they are
> added to the release notes, because that might be a more convenient way
> for end users to get an idea of what changed.  However, "Relnotes: yes"
> does not solve this for those folks.
> 
> It is easy to truncate the file when a new branch is created, just as
> a workflow example, but I think the larger thing here is that while
> there are folks that commit something without "Relnotes: yes" because
> they forgot (or it did not occur to them at the time that it is
> a user-visible change), it can be equally difficult to remember to
> update a file specifically dedicated to this.
> 
> All that said, having at least a sample text of what to include would be
> extremely helpful, at least for me, as sometimes I have to ping
> committers out-of-band to understand why a particular commit was flagged
> as "Relnotes: yes".
> 
> Hopefully all that made sense.  :)

It makes sense to me.  I think the idea is that "Relnotes: yes" is
advisory and serves as a reminder that the commit should get a release
note; committers may forget or not want to write RELNOTES entries for
some reason.  Similar to how "MFC after" is advisory and doesn't
guarantee that an MFC has been done after any particular point.  re@
would need to scan commits for Relnotes tags that don't have entries in
RELNOTES.  Since RELNOTES can be updated after the fact, this set
would hopefully be small.

Regarding whether RELNOTES entries should be removed, I would prefer to
keep them at least until head is branched.  They would serve as useful
documentation to users, and if there are multiple people compiling
release notes they can synchronize in other ways.  At least, I would
wait for it to become a problem before trying to solve it by removing
entries from RELNOTES.