Date: Sun, 23 Jun 2019 22:05:45 -0700 (PDT) From: "Rodney W. Grimes" <freebsd-rwg@gndrsh.dnsmgr.net> To: Warner Losh <imp@bsdimp.com> Cc: "Rodney W. Grimes" <freebsd-rwg@gndrsh.dnsmgr.net>, "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: <201906240505.x5O55j42042161@gndrsh.dnsmgr.net> In-Reply-To: <CANCZdfpqDmB4yrNC%2B_nDyo=J_V=FpSF_228Fwe1xwFzcUmY3Bg@mail.gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
> > > > > 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@. > > > > I'm starting to think that maybe we have one RELNOTES per repo at the top. I was only thinking for /usr/src, aka ^/head/base/ to start with, as I do not know that we generate release notes stuff like this covering the ports or doc tree, though I certainly agree that the future could expand to those areas. > It should be the running list of everything, in markdown format in a > stylized format so we can parse it mechanically. No special permissions > needed, no funky language to learn, no tools to install. Strike markdown, as Both Glen and myself have expressed pure ascii text just like UPDATING is the path of least resistance. I might be convinced of a very very lightweight xml like thing for parsing purposes, ie the rXXXXXX needs to be locatable. > We can merge it with a script. We can make sure that all the relnotes: yes > entries in the repo have an entry in RELNOTES via a script (or we could > just add the commit message as a boiler plate via a script automatically > via a cron job that runs daily / weekly). Yes, but this needs some more though, even just the one liner I sighted in an earlier reply is fine for an RE@ working on the notes, but perhaps having the whole commit message added by the automation might lead to a shorter cycle time in processing them. > > Then it's all there, and we don't have to keep book in multiple files / > formats / etc. Developers can get an entry in there with a single line, or > they can write their own custom entry if the commit message isn't right. > > Tech writers could also word-smith things as we go when they have time so > it's not a huge burden at the end. And people can look along with svnweb / > github (if it's markdown, it will look pretty automatically on github). > > And it fits in with the efforts to modernize doc process since it gets > everybody thinking about and contributing content. > > Then at release time we parse the markdown file from the 3 repos and > convert it to whatever format doc is using and we're done. > > But regardless of the outcome, having it documented in the developer's > handbook would be best. Other than I do not know of any release notes: yes type things that come from doc/ or ports/ this is all in line with what I had modeled in my mind and was evolving as I had discussions with Glen about it. Oh, and pure simple text files, though as I stated earlier, very light xmlish tagging might be ok. Initially I just wanted a way to record the missed Relnotes: Y entires, as that in itself is a huge step forward in creating more complete release notes. The collection of all the properly done commits is trivial, merging those 2 list is also trivial. The conversion of a commit message to a release notes message is not so trivial, but also not massivly complex, but is a single threaded (one person usually does all that work, Glen or the lead RE for that release.) Having this work shareable would be a huge win. And like UPDATING a minimal set of self documentation in the top of the file would probably go further than anything off in the developers handbook. Oh, and it is also possible to use this to do a: r456789: Relnotes: NO, commit message is incorrect r456789 was reverted in r456987 to record the fact that there is no need to mention that specific commit in the release notes, it was erroniously marked, or become irrelevant for some reason, aka revert, etc... > Warner -- Rod Grimes rgrimes@freebsd.org
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201906240505.x5O55j42042161>