release notes file

[Glen Barber]

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

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/20190623/ddacae27/attachment.sig>