Date: Mon, 24 Jun 2019 12:28:26 -0700 From: Cy Schubert <Cy.Schubert@cschubert.com> To: Warner Losh <imp@bsdimp.com> Cc: Cy Schubert <Cy.Schubert@cschubert.com>, "Rodney W. Grimes" <freebsd-rwg@gndrsh.dnsmgr.net>, "freebsd-hackers@freebsd.org" <freebsd-hackers@freebsd.org>, "Bjoern A. Zeeb" <bz@freebsd.org>, Mark Johnston <markj@freebsd.org>, FreeBSD Release Engineering Team <re@freebsd.org> Subject: Re: release notes file Message-ID: <201906241928.x5OJSQhm005255@slippy.cwsent.com> In-Reply-To: Message from Warner Losh <imp@bsdimp.com> of "Mon, 24 Jun 2019 11:45:16 -0600." <CANCZdfomLMvFN4%2BiGh3q-j%2BgCZqP5t0feV7hO2DX=zdhne0rng@mail.gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
In message <CANCZdfomLMvFN4+iGh3q-j+gCZqP5t0feV7hO2DX=zdhne0rng@mail.gma il.com> , Warner Losh writes: > --000000000000b1250d058c156094 > Content-Type: text/plain; charset="UTF-8" > > On Mon, Jun 24, 2019 at 11:06 AM Cy Schubert <Cy.Schubert@cschubert.com> > 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 > > ><Cy.Schubert@cschubert.com> > > >> wrote: > > >> > > >> > On June 23, 2019 5:36:16 PM PDT, Mark Johnston <markj@freebsd.org> > > >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 <Cy.Schubert@cschubert.com> FreeBSD UNIX: <cy@FreeBSD.org> Web: http://www.FreeBSD.org The need of the many outweighs the greed of the few.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201906241928.x5OJSQhm005255>