Date: Sun, 23 Jun 2019 17:53:40 -0700 (PDT) From: "Rodney W. Grimes" <freebsd-rwg@gndrsh.dnsmgr.net> To: Mark Johnston <markj@freebsd.org> Cc: "Bjoern A. Zeeb" <bz@freebsd.org>, freebsd-hackers@freebsd.org, re@freebsd.org Subject: Re: release notes file Message-ID: <201906240053.x5O0rexU041293@gndrsh.dnsmgr.net> In-Reply-To: <20190624003616.GA90409@raichu>
next in thread | previous in thread | raw e-mail | index | archive | help
> 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? I echo your concerns. > > 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. Very much my position on the issue of a simple text file as src/RELNOTES, see other reply. > > 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. Even having you do the simple text in the RELNOTES file is 90% of the work, formatting, markdown, whatever, lets let the doc experts deal with that. This would be a case where we could consistantly delivery a fair bit of simple text for them to work on, and it would take work load off RE@. -- Rod Grimes rgrimes@freebsd.org
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201906240053.x5O0rexU041293>