Date: Mon, 24 Jun 2019 11:45:16 -0600 From: Warner Losh <imp@bsdimp.com> To: Cy Schubert <Cy.Schubert@cschubert.com> Cc: "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: <CANCZdfomLMvFN4%2BiGh3q-j%2BgCZqP5t0feV7hO2DX=zdhne0rng@mail.gmail.com> In-Reply-To: <2BD397BB-FD96-4A06-9263-DD35B2CA494D@cschubert.com> References: <201906241629.x5OGTmpd044504@gndrsh.dnsmgr.net> <2BD397BB-FD96-4A06-9263-DD35B2CA494D@cschubert.com>
next in thread | previous in thread | raw e-mail | index | archive | help
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? > 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. Warner
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CANCZdfomLMvFN4%2BiGh3q-j%2BgCZqP5t0feV7hO2DX=zdhne0rng>