Date: Mon, 24 Jun 2019 09:14:02 -0700 (PDT) From: "Rodney W. Grimes" <freebsd-rwg@gndrsh.dnsmgr.net> To: Cy Schubert <Cy.Schubert@cschubert.com> Cc: freebsd-hackers@freebsd.org, Mark Johnston <markj@freebsd.org>, "Bjoern A. Zeeb" <bz@freebsd.org>, re@freebsd.org Subject: Re: release notes file Message-ID: <201906241614.x5OGE2UH044469@gndrsh.dnsmgr.net> In-Reply-To: <8FF694F5-D5FC-467E-ADBE-244C3A3254D2@cschubert.com>
next in thread | previous in thread | raw e-mail | index | archive | help
> 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. There is no doubt the file needs trimming, it is a matter of what to trim and when to trim it. Further though and discussion on that needs to occur, it is not a clean and dry answer. Technically when you create the branch there are no new commits in that branch that need Relnotes notices, that data is all in the parent branch. The version of the RELNOTES file at this point could be very valuable, or could be noise that clutters the process. I can see that there is the issue of you need to bring over all the parent branch relnotes related entries, that are applicable, so maybe that goes into a seperate section to be weeded through? Glen showed a graph that was probably from some of the discussions I have had with him on this topic. And given he has created more release notes than any of us it is him who has the expertise in what data it is he needs in that creation process, so I would defer the decision to him, though I am sure he is open to inputs. -- Rod Grimes rgrimes@freebsd.org
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201906241614.x5OGE2UH044469>