svn commit: r341759 - in head: contrib/wpa contrib/wpa/hostapd contrib/wpa/hs20/client contrib/wpa/src/ap contrib/wpa/src/common contrib/wpa/src/crypto contrib/wpa/src/drivers contrib/wpa/src/eap_c...

[Rodney W. Grimes]

> On Sun, 2018-12-09 at 23:47 -0700, Warner Losh wrote:
> > On Sun, Dec 9, 2018, 11:40 PM Cy Schubert <Cy.Schubert at cschubert.com
> > wrote:
> > 
> > > 
> > > In message <201812100619.wBA6JB0c064609 at pdx.rh.CN85.dnsmgr.net>,
> > > "Rodney W. Gri
> > > mes" writes:
> > > > 
> > > > > 
> > > > > On Sun, Dec 9, 2018 at 2:03 PM Oliver Pinter <
> > > oliver.pinter at hardenedbsd.org
> > > > 
> > > > > 
> > > > > 
> > > > > wrote:
> > > > > 
> > > > > > 
> > > > > > 
> > > > > > 
> > > > > > On Sunday, December 9, 2018, Warner Losh <imp at bsdimp.com>
> > > > > > wrote:
> > > > > > 
> > > > > > > 
> > > > > > > On Sun, Dec 9, 2018 at 1:09 PM Rodney W. Grimes <
> > > > > > > freebsd at pdx.rh.cn85.dnsmgr.net> wrote:
> > > > > > > 
> > > > > > > > 
> > > > > > > > > 
> > > > > > > > > In message <201812090645.wB96jnso066329 at repo.freebsd.or
> > > > > > > > > g>, Cy
> > > > > > > Schubert
> > > > > > > > 
> > > > > > > > > 
> > > > > > > > > writes:
> > > > > > > > > > 
> > > > > > > > > > Author: cy
> > > > > > > > > > Date: Sun Dec??9 06:45:49 2018
> > > > > > > > > > New Revision: 341759
> > > > > > > > > > URL: https://svnweb.freebsd.org/changeset/base/341759
> > > > > > > > > > 
> > > > > > > > > > Log:
> > > > > > > > > > ? MFV r341618:
> > > > > > > > > > 
> > > > > > > > > > ? Update wpa 2.6 --> 2.7.
> > > > > > > > > Relnotes: yes
> > > > > > > > As an FYI, or maybe a new procedure, doing a reply to
> > > > > > > > a commit message adding relnotes: yes does very little
> > > > > > > > to insure that this commit gets refered to in release
> > > > > > > > notes.
> > > > > > > > 
> > > > > > > > What about we add RELNOTES.missed to the tree
> > > > > > > > next to UPDATING, and when someone forgets to tag
> > > > > > > > the Relnotes:yes into a commit you just follow up
> > > > > > > > with a commit to that file, stating the svn revision
> > > > > > > > which was missing the note and then we have a nice
> > > > > > > > documented and clean way to extract the missing
> > > > > > > > release note items, rather than trying to cull it
> > > > > > > > from a thread in a mail list archive.
> > > > > > > > 
> > > > > > > > The file would get truncated to 0 at appropriate
> > > > > > > > times on various branches.
> > > > > > > > 
> > > > > > > How about just RELNOTES. You put the revision that is
> > > > > > > relevant and
> > > a qui
> > > > 
> > > > ck
> > > > > 
> > > > > > 
> > > > > > > 
> > > > > > > blurb. That way we don't have to look in two places. All
> > > > > > > release
> > > notes g
> > > > 
> > > > o
> > > > > 
> > > > > > 
> > > > > > > 
> > > > > > > in here, no exceptions. You can retroactively tag them, or
> > > > > > > you can
> > > commi
> > > > 
> > > > t
> > > > > 
> > > > > > 
> > > > > > > 
> > > > > > > this as part of commit.
> > > > My one concern is that if we remove the Relnotes: yes line
> > > > from the commits then we may end up totally ignoring the
> > > > need to put entries in RELNOTES, which unlike UPDATING
> > > > do not have consequences if ignored.
> > > > 
> > > > > 
> > > > > > 
> > > > > > 
> > > > > > 
> > > > > > > 
> > > > > > > 
> > > > > > I don't really know SVN, but there wouldn't be a chicken egg
> > > > > > probem
> > > durin
> > > > 
> > > > g
> > > > > 
> > > > > > 
> > > > > > commit time? I mean you would really know the SVN id. So you
> > > > > > could
> > > only a
> > > > 
> > > > dd
> > > > > 
> > > > > > 
> > > > > > a specific revision in a different commit to RELEASE file.
> > > > > > 
> > > > > Generally, you can guess really well, and fix it in the case of
> > > > > a lost
> > > race
> > > > 
> > > > > 
> > > > > easily.
> > > > No reason to guess, if you add the RELNOTES change with the
> > > > commit
> > > > then it is the revision that added the RELNOTES entry, so a log
> > > > view
> > > > of RELNOTES would show you the revision.??If you do it after
> > > > words
> > > > or edit an existing entry in the RELNOTES file that is also
> > > > fairly
> > > > clear as that commit has no other files touched.
> > > > 
> > > > > 
> > > > > 
> > > > > You'd add the release notes text in full to the file, with a
> > > > > pointer
> > > to the
> > > > 
> > > > > 
> > > > > revision(s) for the feature.
> > > > If you modify RELNOTES with the commit adding the feature we
> > > > could easily use a pointer of "this commit", the svn version
> > > > number
> > > > of that added entry is self referencing to the actual change,
> > > > which I actually rather like the idea of.
> > > > 
> > > > > 
> > > > > 
> > > > > Warner
> > > > > 
> > > > > > 
> > > > > > 
> > > > > > > 
> > > > > > > Have a blurb at the top that tells people what
> > > > > > > order to add them in, and you'd be set. We'd then retire
> > > > > > > "relnotes:
> > > yes"
> > > > 
> > > > > 
> > > > > > 
> > > > > > > 
> > > > > > > in
> > > > > > > the commit message. This would also allow 'helpers' to
> > > > > > > format the
> > > RELNOT
> > > > 
> > > > ES
> > > > > 
> > > > > > 
> > > > > > > 
> > > > > > > file as we go rather than having to play 2 years of catch-
> > > > > > > up at
> > > major
> > > > 
> > > > > 
> > > > > > 
> > > > > > > 
> > > > > > > branch times.
> > > > Yes.??You could actually "delete" an entry from RELNOTES once a
> > > > proper entry in the actual release notes had been created, such
> > > > that RELNOTES is really a list of pending items.
> > > > 
> > > > > 
> > > > > > 
> > > > > > > 
> > > > > > > 
> > > > > > > Having it in the commit message just doesn't work, and this
> > > > > > > is one
> > > of ma
> > > > 
> > > > ny
> > > > > 
> > > > > > 
> > > > > > > 
> > > > > > > reasons: Cy forgot. Other times I'll do something and it's
> > > > > > > only a
> > > month
> > > > 
> > > > > 
> > > > > > 
> > > > > > > 
> > > > > > > later I realize it needs to be in the release notes after
> > > > > > > some
> > > issue has
> > > > 
> > > > > 
> > > > > > 
> > > > > > > 
> > > > > > > come up.... Other times I put relnotes: yes in only to
> > > > > > > realize
> > > that's my
> > > > 
> > > > > 
> > > > > > 
> > > > > > > 
> > > > > > > vanity talking, and nobody else cares.
> > > > I agree, what we have now works poorly.
> > > Forgetting, yes, but also a hmmm moment.
> > > 
> > > Initially my thinking was a file in doc/. Or maybe something like
> > > the
> > > vuxml port where we fill in the blanks and make validate to make
> > > sure
> > > all the i's are dotted and t's crossed. It's a little extra work
> > > for
> > > committers but would help re@ immensely, and get the details in
> > > from
> > > the get-go.
> > > 
> > 
> > My thought was a low friction,??proximate way to do a ticker of important
> > changes. Doc repo is too hard. Too much friction. A simple extra file puts
> > it all in one, easy to find and edit place... it can cause other things to
> > happen, further away. But it needs to be close by.
> > 
> 
> I agree that a RELNOTES file as plain ascii text will be the easiest
> thing for src committers to work with, and being easy will definitely
> improve the odds of being updated.
> 
> We have empirical data on src committers updating an xml file in the
> docs repo, based on documenting version number bumps, and it all too
> often doesn't happen, I think laregely because it's a big hassle and
> it's out of sight in another repo.

On this position I agree fully with Warner and Ian, simple and easy
is very important here, and IMHO this RELNOTES file is a simple fix
for the missing RelNotes: yes issue.  It also allows the committer
to actually say more than just "yes".

Also note I do not think we would be requireing more than a simple
"this should be mentioned in release notes", defanitly are not asking
for publication ready notes, though those would be gladly accepted!

Can I ask that the community now allows the RE@ team to discuss
this internally and come back with a proposal?  Feel free to continue
discussing on this thread, I'll try to incorporate any items brought
up into our discussion.

Thanks,
-- 
Rod Grimes                                                 rgrimes at freebsd.org