Date: Mon, 24 Jun 2019 09:29:48 -0700 (PDT) From: "Rodney W. Grimes" <freebsd-rwg@gndrsh.dnsmgr.net> To: Warner Losh <imp@bsdimp.com> Cc: Cy Schubert <Cy.Schubert@cschubert.com>, "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: <201906241629.x5OGTmpd044504@gndrsh.dnsmgr.net> In-Reply-To: <CANCZdfpSL34g15EyZe5s1mE=xOCg_31Jf8yqNFPC5PCWbBkDCA@mail.gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
> 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 -- Rod Grimes rgrimes@freebsd.org
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201906241629.x5OGTmpd044504>