Date: Mon, 24 Jun 2019 10:06:02 -0700 From: Cy Schubert <Cy.Schubert@cschubert.com> To: "Rodney W. Grimes" <freebsd-rwg@gndrsh.dnsmgr.net>, Warner Losh <imp@bsdimp.com> Cc: "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: <2BD397BB-FD96-4A06-9263-DD35B2CA494D@cschubert.com> In-Reply-To: <201906241629.x5OGTmpd044504@gndrsh.dnsmgr.net> References: <201906241629.x5OGTmpd044504@gndrsh.dnsmgr.net>
next in thread | previous in thread | raw e-mail | index | archive | help
On June 24, 2019 9:29:48 AM PDT, "Rodney W=2E Grimes" <freebsd-rwg@gndrsh= =2Ednsmgr=2Enet> wrote: >> On Mon, Jun 24, 2019 at 9:44 AM Cy Schubert ><Cy=2ESchubert@cschubert=2Ecom> >> wrote: >>=20 >> > On June 23, 2019 5:36:16 PM PDT, Mark Johnston <markj@freebsd=2Eorg> >wrote: >> > >On Sun, Jun 23, 2019 at 11:23:57PM +0000, Bjoern A=2E 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=2E >> > >> > 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=2E I would like to propose adding a >> > >> > top-level >> > >> > RELNOTES file instead, which like UPDATING would document >notes for >> > >> > specific commits=2E It would be truncated every time the head >branch >> > >is >> > >> > forked, and changes to it would be MFCed=2E This fixes the >> > >> > above-mentioned problems and would hopefully reduce the amount >of >> > >time >> > >> > needed by re@ to compile release notes=2E >> > >> >> > >> Hooray=2E 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=2E0 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)=2E 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=2E 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)=2E >> > >> >> > >> Oh, with that release notes are written automatically and you >are >> > >still >> > >> responsible for that your stuff is in there=2E 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 =2E=2E on our web server under /releases/ where they >belong >> > >=2E=2E >> > >> >> > >> 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=2E There are lots >of >> > >__FreeBSD_version bumps that go undocumented until someone else >goes in >> > >and fills in the missing entries=2E A plain-text file in src repo >for >> > >src >> > >release notes is low-friction and creates only marginally more >work for >> > >RE=2E "What's cooking for 13?" can just point to the copy of >RELNOTES in >> > >svnweb=2E >> > > >> > >That said, I personally would try to commit my release notes to a >doc >> > >repo file if one existed=2E I've spent a few minutes trying to >compile >> > >the 12=2E0 notes on my desktop and have not been able to get past, >> > >"cannot >> > >parse >http://www=2EFreeBSD=2Eorg/XML/share/xml/freebsd-xhtml-release=2Exsl"=2E >> > >So, I'm probably not a good person to set up release notes for >13=2E0=2E I >> > >will help fill in entries for commits since the 12=2E0 if someone >else >> > >does that setup=2E >> > >_______________________________________________ >> > >freebsd-hackers@freebsd=2Eorg mailing list >> > >https://lists=2Efreebsd=2Eorg/mailman/listinfo/freebsd-hackers >> > >To unsubscribe, send any mail to >> > >"freebsd-hackers-unsubscribe@freebsd=2Eorg" >> > >> > Src and ports should each have their own RELNOTES file=2E >> > >> > The only operational concern I have is trimming the file, probably >when a >> > branch goes EOL=2E >> > >>=20 >> I'd add truncating the file on -current to the list of things we do >when we >> branch=2E then we can MFC RELNOTES as we MFC the features they >describe=2E > >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=2E > >Howerver there is 1 point on head/ to truncate the file=2E >That is when we create a new =2E0 branch as that is the tree state >that has nothing to put in the release notes=2E This may be the >most sane path forward that I had not thought of before=2E All >other branched versions can just continue to grow until EOL=2E >This bounds the file to about a 2=2E5 year collection in head/, >and a 5=2E0 year collection in stable/=2E >It may make since to truncate on stable/X when stable/X=2EY's >are created=2E > >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=2E > >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=20 >head commit that makes it harded to go find the MFC and see >if there was merge munging to make it work=2E > >> Warner Which is why trimming at branch EOL probably makes the most sense=2E It's = simple and easy to implement=2E As for what to do about MFCs and more specifically conflicts, conflicts wi= ll be unavoidable=2E IMO conflicts with RELNOTES will be as likely as with = UPDATING or Obsoletefiles=2E=20 --=20 Pardon the typos and autocorrect, small keyboard in use=2E Cheers, Cy Schubert <Cy=2ESchubert@cschubert=2Ecom> FreeBSD UNIX: <cy@FreeBSD=2Eorg> Web: http://www=2EFreeBSD=2Eorg The need of the many outweighs the greed of the few=2E
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?2BD397BB-FD96-4A06-9263-DD35B2CA494D>