release notes file

[Glen Barber]

On Sun, Jun 23, 2019 at 05:09:59PM -0400, Mark Johnston wrote:
> 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.
> 

To your latter point, removing the RELNOTES entries, this is what I sort
of had in mind:

 head -> stable/X -> releng/X.Y:
  head/RELNOTES gets truncated after stable/X is created;
  stable/X gets truncated after releng/X.Y is created

For point releases, the workflow is similar as it just excludes head:
 stable/X -> releng/X.Y:
  stable/X gets truncated after releng/X.Y is created

In other words, there would be no arbitrarily-long file, but there
would potentially be some overlap for a major release where a dot-zero
release has last-minute new stuff that should be in release notes; it
would grow and shrink as development happens.

Or, this is how I see it being most beneficial to RE when it comes to
writing release notes, at least.

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