Date: Sun, 23 Jun 2019 17:47:09 -0700 (PDT) From: "Rodney W. Grimes" <freebsd-rwg@gndrsh.dnsmgr.net> To: Glen Barber <gjb@freebsd.org> Cc: "Bjoern A. Zeeb" <bz@freebsd.org>, freebsd-hackers@freebsd.org, Mark Johnston <markj@freebsd.org>, re@freebsd.org Subject: Re: release notes file Message-ID: <201906240047.x5O0l98i041275@gndrsh.dnsmgr.net> In-Reply-To: <20190623234845.GE41944@FreeBSD.org>
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? The file needs to live in src/ as this is to catch the missed Release Notes: Y thing and if you put it in doc repo src committers have hard access to even make a commit to it. Ideally some people well want to commit to src/RELNOTES at the same time as they make there commit to the tree, helping the release engineering team out a great deal. For those forgotten Release Notes: Yes items one simple does a top level sparse checkout of ^/head/base add an entry to RELNOTES stating what rXXXXXX it applies to and what was left out, can even be as simple as "Forgot Relnotes: Y". I was working on a proposal while part of RE to do much of this, that proposal was shelfed when I exited RE. > > 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? > > Very. > > But, I have one non-important nit -- the file in question does not need > to be formatted for the documentation language of the day. In other > words, I do not see this file as a "copy/paste from here to there and be > done with it" sort of thing; i.e., grammar nits, clarifications that > stray from the original commit log (or commit log intent), etc. That was also my feelings, the file should be extremly simple, and rough. It may have 2 or more parts. It should be possible to automatic collecting of Relnotes: foo entries from commits and making sure they all have entries in this file. The 2 part thing is I had a part that is kinda RE only, that is where RE tracks and builds the fuller text from the simple entries added by developers or the releasenotes tag. The simpler entries are marked off as "processed by RE (username@) on date" so that they could be worked on in parallel. I felt this could be expanded to people outside of RE once more experienced was gained and operational procedures established. Examples: r123342: Relnotes: Yes forgot to flag in original commit This is a committer cleaning up a forgotten flag r123344: Relnotes: Yes added by autobot1 on 2019/06/21 This is the type of thing a weekly cronjob, or even a postcommit hook script does. What it looks like after a RE/Doc person deals with it: r123344: Relnotes: Yes proccess by RE (gjb@) on 2019/06/22 ... PART 2 of file: r12344: This commit added the new feature reserve parachute to appliction pilot ejection. Please exercise care when using it as it is experimental and the riggers are still learning to pack properly. These would be visible to all committers so if someone makes a mistake discribing a change that is going into release notes feedback can be provided in very short order. > > When re@ requests clarification on commits or prods committers for > things that may not have otherwise made it into the release notes, it > isn't sent as a "please send us the properly-formatted XML entry" or > some such thing, so personally, I am perfectly fine with a 80-character > line-length raw plain-text entry. Yep > Just my $0.02 USD. > Glen Here, have some change.... $0.01 -- Rod Grimes rgrimes@freebsd.org
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201906240047.x5O0l98i041275>