Date: Wed, 26 Jun 2019 20:45:15 -0400 From: Mark Johnston <markj@freebsd.org> To: freebsd-hackers@freebsd.org Cc: re@freebsd.org Subject: Re: release notes file Message-ID: <20190627004515.GB73130@raichu> In-Reply-To: <20190623191818.GA84365@raichu> References: <20190623191818.GA84365@raichu>
next in thread | previous in thread | raw e-mail | index | archive | help
On Sun, Jun 23, 2019 at 03:18:18PM -0400, 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. To be clear, my aim here is to help ensure that new features are documented close to when they are committed. Today, release notes are compiled only shortly before a release, which means that re@ has to go through all of the new commits looking for relnotes tags and hope that they didn't miss anything. A RELNOTES file helps prevent things from falling through the cracks and reduces the amount of work required of re@. > For example: > > Index: RELNOTES > =================================================================== > --- RELNOTES (nonexistent) > +++ RELNOTES (working copy) > @@ -0,0 +1,8 @@ > +Release notes for FreeBSD 13.0. > + > +r349286: > + swapon(8) can now erase a swap device immediately before > + enabling it, similar to newfs(8)'s -E option. This behaviour > + can be specified by adding -E to swapon(8)'s command-line > + parameters, or by adding the "trimonce" option to a swap > + device's /etc/fstab entry. > > What do folks think? To summarize what I think are the important points from the discussion that ensued: - RELNOTES would be useful. In other words, I didn't see any opposition to the idea. - It's not clear when and how RELNOTES should be truncated. Since this is really an re@ policy question, it doesn't block RELNOTES from being added to the tree. So, I will ignore this issue and let them figure it out once we actually come up to the next release and have some experience. - It's not clear how best to handle MFCs of RELNOTES. I will propose that we simply not MFC RELNOTES for now: given head's copy of RELNOTES, one can easily determine whether any of the referenced revisions are in a stable branch. - RELNOTES should be easy to parse. - RELNOTES is not intended to be presented directly to users; it is a log that can be used to generate user-friendlier documentation. So, it will not be installed and entries should be in plain text. - (Not actually discussed, but my own thoughts:) There is some overlap with UPDATING; some things that I would consider release notes are documented there. As I understand it, the goal of UPDATING is to document changes that may trip up users who build from source: KBI changes, renames, removals, and so on. RELNOTES is for users of binary FreeBSD releases. So, there may be some overlap, but in general I think we should avoid using UPDATING to document routine changes like contrib/ updates. I put a proposed initial version here: https://reviews.freebsd.org/D20762
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20190627004515.GB73130>