Date: Sun, 23 Jun 2019 20:01:43 -0600 From: Warner Losh <imp@bsdimp.com> To: "Rodney W. Grimes" <freebsd-rwg@gndrsh.dnsmgr.net> Cc: Mark Johnston <markj@freebsd.org>, "freebsd-hackers@freebsd.org" <freebsd-hackers@freebsd.org>, "Bjoern A. Zeeb" <bz@freebsd.org>, FreeBSD Release Engineering Team <re@freebsd.org> Subject: Re: release notes file Message-ID: <CANCZdfpqDmB4yrNC%2B_nDyo=J_V=FpSF_228Fwe1xwFzcUmY3Bg@mail.gmail.com> In-Reply-To: <201906240053.x5O0rexU041293@gndrsh.dnsmgr.net> References: <20190624003616.GA90409@raichu> <201906240053.x5O0rexU041293@gndrsh.dnsmgr.net>
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. 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. 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). 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. Warner
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CANCZdfpqDmB4yrNC%2B_nDyo=J_V=FpSF_228Fwe1xwFzcUmY3Bg>