From owner-freebsd-hackers@freebsd.org Mon Jun 24 19:28:40 2019 Return-Path: Delivered-To: freebsd-hackers@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 3316F15D70FC for ; Mon, 24 Jun 2019 19:28:40 +0000 (UTC) (envelope-from cy.schubert@cschubert.com) Received: from smtp-out-no.shaw.ca (smtp-out-no.shaw.ca [64.59.134.9]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "Client", Issuer "CA" (not verified)) by mx1.freebsd.org (Postfix) with ESMTPS id BDD28845DD; Mon, 24 Jun 2019 19:28:38 +0000 (UTC) (envelope-from cy.schubert@cschubert.com) Received: from spqr.komquats.com ([70.67.125.17]) by shaw.ca with ESMTPA id fUdghNfRRsAGkfUdhhjtnj; Mon, 24 Jun 2019 13:28:31 -0600 X-Authority-Analysis: v=2.3 cv=WeVylHpX c=1 sm=1 tr=0 a=VFtTW3WuZNDh6VkGe7fA3g==:117 a=VFtTW3WuZNDh6VkGe7fA3g==:17 a=jpOVt7BSZ2e4Z31A5e1TngXxSK0=:19 a=kj9zAlcOel0A:10 a=dq6fvYVFJ5YA:10 a=xfDLHkLGAAAA:8 a=YxBL1-UpAAAA:8 a=iKhvJSA4AAAA:8 a=6I5d2MoRAAAA:8 a=ihLmRic6LxAFEx1RyPEA:9 a=rVnsKfbM7t8OGkJA:21 a=-xq0APv4xBvugdXA:21 a=CjuIK1q_8ugA:10 a=IfaqVvZgccqrtc8gcwf2:22 a=Ia-lj3WSrqcvXOmTRaiG:22 a=odh9cflL3HIXMm4fY7Wr:22 a=IjZwj45LgO3ly-622nXo:22 Received: from slippy.cwsent.com (slippy8 [10.2.2.6]) by spqr.komquats.com (Postfix) with ESMTPS id 3B00DD13; Mon, 24 Jun 2019 12:28:27 -0700 (PDT) Received: from slippy.cwsent.com (localhost [127.0.0.1]) by slippy.cwsent.com (8.15.2/8.15.2) with ESMTP id x5OJSQMR005258; Mon, 24 Jun 2019 12:28:26 -0700 (PDT) (envelope-from Cy.Schubert@cschubert.com) Received: from slippy (cy@localhost) by slippy.cwsent.com (8.15.2/8.15.2/Submit) with ESMTP id x5OJSQhm005255; Mon, 24 Jun 2019 12:28:26 -0700 (PDT) (envelope-from Cy.Schubert@cschubert.com) Message-Id: <201906241928.x5OJSQhm005255@slippy.cwsent.com> X-Authentication-Warning: slippy.cwsent.com: cy owned process doing -bs X-Mailer: exmh version 2.9.0 11/07/2018 with nmh-1.7.1 Reply-to: Cy Schubert From: Cy Schubert X-os: FreeBSD X-Sender: cy@cwsent.com X-URL: http://www.cschubert.com/ To: Warner Losh cc: Cy Schubert , "Rodney W. Grimes" , "freebsd-hackers@freebsd.org" , "Bjoern A. Zeeb" , Mark Johnston , FreeBSD Release Engineering Team Subject: Re: release notes file In-Reply-To: Message from Warner Losh of "Mon, 24 Jun 2019 11:45:16 -0600." Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Date: Mon, 24 Jun 2019 12:28:26 -0700 X-CMAE-Envelope: MS4wfPq/qw2KuS0c5Y9qS13L278qG8NDjv+xorAToUMVwBtVqfpzXbeeGMsvouuCk9xFxt3a6Gq4oc+nltoQIyxlinaTSplsyVBBV9UF4G6cpXrswh633zvK EgcG0SjkM9WqHGDgwSYe4f4/vvoZN9/ZhCIXs91z0eDIHwoCRmC8j4qXPO6SmOnGbEcQsf/Wz5ywFx8NA8z74+67pxcy9/ykCYiU6UnR2kEBPEycGEhKW0w0 Ps0IVEUlBgkao3nyXxpmaLviNgfJXIcVM4Yy61Gdm/3JhklT5VbK/dU3t1H9aALU5pPY7tUnOZNFEOyXjxcrFa7dRxRbTFMIYNNl4TTCQ/c= X-Rspamd-Queue-Id: BDD28845DD X-Spamd-Bar: ----- Authentication-Results: mx1.freebsd.org X-Spamd-Result: default: False [-5.24 / 15.00]; TO_DN_EQ_ADDR_SOME(0.00)[]; RCVD_VIA_SMTP_AUTH(0.00)[]; HAS_REPLYTO(0.00)[Cy.Schubert@cschubert.com]; TO_DN_SOME(0.00)[]; MV_CASE(0.50)[]; HAS_XAW(0.00)[]; MX_GOOD(-0.01)[cached: spqr.komquats.com]; NEURAL_HAM_SHORT(-0.99)[-0.989,0]; RCPT_COUNT_SEVEN(0.00)[7]; RECEIVED_SPAMHAUS_PBL(0.00)[17.125.67.70.zen.spamhaus.org : 127.0.0.11]; RCVD_IN_DNSWL_LOW(-0.10)[9.134.59.64.list.dnswl.org : 127.0.5.1]; R_DKIM_NA(0.00)[]; ASN(0.00)[asn:6327, ipnet:64.59.128.0/20, country:CA]; MIME_TRACE(0.00)[0:+]; FROM_EQ_ENVFROM(0.00)[]; ARC_NA(0.00)[]; NEURAL_HAM_MEDIUM(-1.00)[-1.000,0]; RCVD_COUNT_FIVE(0.00)[5]; REPLYTO_EQ_FROM(0.00)[]; FROM_HAS_DN(0.00)[]; NEURAL_HAM_LONG(-1.00)[-1.000,0]; MIME_GOOD(-0.10)[text/plain]; RCVD_TLS_LAST(0.00)[]; TO_MATCH_ENVRCPT_SOME(0.00)[]; R_SPF_NA(0.00)[]; IP_SCORE(-2.54)[ip: (-6.79), ipnet: 64.59.128.0/20(-3.27), asn: 6327(-2.54), country: CA(-0.09)] X-BeenThere: freebsd-hackers@freebsd.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Technical Discussions relating to FreeBSD List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 24 Jun 2019 19:28:40 -0000 In message , Warner Losh writes: > --000000000000b1250d058c156094 > Content-Type: text/plain; charset="UTF-8" > > On Mon, Jun 24, 2019 at 11:06 AM Cy Schubert > wrote: > > > On June 24, 2019 9:29:48 AM PDT, "Rodney W. Grimes" < > > freebsd-rwg@gndrsh.dnsmgr.net> wrote: > > >> On Mon, Jun 24, 2019 at 9:44 AM Cy Schubert > > > > > >> wrote: > > >> > > >> > On June 23, 2019 5:36:16 PM PDT, Mark Johnston > > >wrote: > > >> > >On Sun, Jun 23, 2019 at 11:23:57PM +0000, Bjoern A. Zeeb wrote: > > >> > >> On 23 Jun 2019, at 19:18, 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. > > >> > >> > > >> > >> Hooray. Can we put that file into the doc repo, so that the > > >ports > > >> > >> people, and the docs people, and all other kinds of hats can put > > >> > >things > > >> > >> in there as well? > > >> > > > > >> > >Virtually all of the 12.0 release notes are for src/ (there are 4 > > >lines > > >> > >for ports/pkg and 1 line for docs, and the latter describes a new > > >man > > >> > >page in src). Why is it important to have a single place for > > >everyone > > >> > >to commit their entries? > > >> > > > > >> > >> Oh, the release notes go into the doc repo anyway. Can we just > > >put > > >> > >them > > >> > >> in the right place and just fill them from a skeleton where they > > >> > >should > > >> > >> be and naturally grow the document (feel free to use a different > > >> > >markup > > >> > >> language once doc is ready for that). > > >> > >> > > >> > >> Oh, with that release notes are written automatically and you > > >are > > >> > >still > > >> > >> responsible for that your stuff is in there. And the release > > >notes > > >> > >only > > >> > >> need an editing pass in the end? > > >> > >> > > >> > >> And the wiki pages like ?What?s cooking for 13?? or similar > > >could > > >> > >> just vanish as we?d have these updated at least every 10 minutes > > >> > >> automatically .. on our web server under /releases/ where they > > >belong > > >> > >.. > > >> > >> > > >> > >> How amazing would that be? > > >> > > > > >> > >I would guess that many src committers simply won't add release > > >notes > > >> > >if > > >> > >they have to commit to a second repository and use some unfamiliar > > >> > >markup format and worry about validating the file. There are lots > > >of > > >> > >__FreeBSD_version bumps that go undocumented until someone else > > >goes in > > >> > >and fills in the missing entries. A plain-text file in src repo > > >for > > >> > >src > > >> > >release notes is low-friction and creates only marginally more > > >work for > > >> > >RE. "What's cooking for 13?" can just point to the copy of > > >RELNOTES in > > >> > >svnweb. > > >> > > > > >> > >That said, I personally would try to commit my release notes to a > > >doc > > >> > >repo file if one existed. I've spent a few minutes trying to > > >compile > > >> > >the 12.0 notes on my desktop and have not been able to get past, > > >> > >"cannot > > >> > >parse > > >http://www.FreeBSD.org/XML/share/xml/freebsd-xhtml-release.xsl". > > >> > >So, I'm probably not a good person to set up release notes for > > >13.0. I > > >> > >will help fill in entries for commits since the 12.0 if someone > > >else > > >> > >does that setup. > > >> > >_______________________________________________ > > >> > >freebsd-hackers@freebsd.org mailing list > > >> > >https://lists.freebsd.org/mailman/listinfo/freebsd-hackers > > >> > >To unsubscribe, send any mail to > > >> > >"freebsd-hackers-unsubscribe@freebsd.org" > > >> > > > >> > Src and ports should each have their own RELNOTES file. > > >> > > > >> > The only operational concern I have is trimming the file, probably > > >when a > > >> > branch goes EOL. > > >> > > > >> > > >> I'd add truncating the file on -current to the list of things we do > > >when we > > >> branch. then we can MFC RELNOTES as we MFC the features they > > >describe. > > > > > >I disagree, truncating the file on -current destroys the list of > > >changes that are still in current that need to get into the next > > >set of release notes. > > > > > >Howerver there is 1 point on head/ to truncate the file. > > >That is when we create a new .0 branch as that is the tree state > > >that has nothing to put in the release notes. This may be the > > >most sane path forward that I had not thought of before. All > > >other branched versions can just continue to grow until EOL. > > >This bounds the file to about a 2.5 year collection in head/, > > >and a 5.0 year collection in stable/. > > >It may make since to truncate on stable/X when stable/X.Y's > > >are created. > > > > > >I think we need to be fairly careful with the MFCing of this, > > >that may work fine for things that are commited with a RELNOTES > > >entry, something in the back of my head is screaming lots of > > >merge conflicts but I can not put a solid finger on it. > > > > > >Something just hit me, what commit number goes in this file, > > >if we list it by rXXXXXX of head, that has a rYYYYYY when MFC'ed, > > >probably need to track both? Which means all existing entries get > > >an added line at stable/X creation to indicated the commit that > > >created the branch? If we try to simplify and only track by > > >head commit that makes it harded to go find the MFC and see > > >if there was merge munging to make it work. > > > > > >> Warner > > > > Which is why trimming at branch EOL probably makes the most sense. It's > > simple and easy to implement. > > > > I don't understand this at all. When we branch a new stable release, we > know that on the new current release we have nothing not in the release > notes file. What does branch EOL have to do with that? You're right. My point was to avoid some kind of complicated scheme. > > > > As for what to do about MFCs and more specifically conflicts, conflicts > > will be unavoidable. IMO conflicts with RELNOTES will be as likely as with > > UPDATING or Obsoletefiles. > > > > Yea. If we keep the structure of the file super simple (like markdown), > then it doesn't matter. You fix the conflicts and go. The merged version > need not be tracked since you know it's merged if it is in RELNOTES, and > most MFCs don't replicate the full context of the original commit any, but > just have a pointer to it. -- Cheers, Cy Schubert FreeBSD UNIX: Web: http://www.FreeBSD.org The need of the many outweighs the greed of the few.