Date: Mon, 24 Jun 2019 09:47:32 -0600 From: Warner Losh <imp@bsdimp.com> To: Cy Schubert <Cy.Schubert@cschubert.com> Cc: "freebsd-hackers@freebsd.org" <freebsd-hackers@freebsd.org>, Mark Johnston <markj@freebsd.org>, "Bjoern A. Zeeb" <bz@freebsd.org>, FreeBSD Release Engineering Team <re@freebsd.org> Subject: Re: release notes file Message-ID: <CANCZdfpSL34g15EyZe5s1mE=xOCg_31Jf8yqNFPC5PCWbBkDCA@mail.gmail.com> In-Reply-To: <8FF694F5-D5FC-467E-ADBE-244C3A3254D2@cschubert.com> References: <20190623191818.GA84365@raichu> <55030704-F521-4D6E-9B56-4B7F65EFFC38@FreeBSD.org> <20190624003616.GA90409@raichu> <8FF694F5-D5FC-467E-ADBE-244C3A3254D2@cschubert.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 =E2=80=9CWhat=E2=80=99s cooking for 13?=E2=80= =9D or similar could > >> just vanish as we=E2=80=99d have these updated at least every 10 minut= es > >> 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. Warner
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CANCZdfpSL34g15EyZe5s1mE=xOCg_31Jf8yqNFPC5PCWbBkDCA>