Date: Thu, 27 Jun 2019 02:10:17 +0000 From: Glen Barber <gjb@freebsd.org> To: Mark Johnston <markj@freebsd.org> Cc: freebsd-hackers@freebsd.org, re@freebsd.org Subject: Re: release notes file Message-ID: <20190627021017.GY13146@FreeBSD.org> In-Reply-To: <20190627004515.GB73130@raichu> References: <20190623191818.GA84365@raichu> <20190627004515.GB73130@raichu>
next in thread | previous in thread | raw e-mail | index | archive | help
--M/v0iXgzSsdULkoO Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Wed, Jun 26, 2019 at 08:45:15PM -0400, Mark Johnston wrote: > On Sun, Jun 23, 2019 at 03:18:18PM -0400, Mark Johnston wrote: > > Hi, > >=20 > > 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. >=20 > 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@. >=20 > > For example: > >=20 > > Index: RELNOTES > > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > > --- 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. > >=20 > > What do folks think? >=20 > To summarize what I think are the important points from the discussion > that ensued: >=20 > - RELNOTES would be useful. In other words, I didn't see any > opposition to the idea. I did not see opposition either. > - 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. Here is my view of the world in this regard. Release notes between X.Y-1 and X.Y should be differences between X.Y-1 and X.Y. Major version releases are trickier, because there's the open-ended question of "against what release do we compare the release notes?" To be honest, I still do not have a good metric upon which to base the latter, but just throwing it at the wall to see what sticks. > - 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. For 12.0 and later, release notes files (the XML files) exist in the doc tree. For 11.x and earlier, they exist in src, but since I have been personally involved in release notes for the past 12 or so releases, I have never done an MFC from head to stable for the release/doc directory. It does indeed cause merge conflicts, and more importantly, the revision numbers associated with the commit are wrong unless manually fixed. My $0.02 USD is to commit to the file on head and stable branches directly, and *never* do an MFC to the RELNOTES file. It is, in my experience, just not worth dealing with the conflicts. > - RELNOTES should be easy to parse. This is why I am in preference of a plain-text file, wrapped at 80 characters. I do not necessarily care about nonexistent parsing capabilities in other software at the moment. > - 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. Yes. (See previous comment.) > - (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. >=20 100% agreed. Furthermore, the RELNOTES file can replace things like "rNNNNNN: Updated Clang (and friends) to upstream 7.0.1." easily with "rNNNNNN: Updated Clang (and friends) to upstream 8.0.0." That, in particular, eliminates some of the relnotes.xml reordering (based on revision numbers for ease, no other particular reason) when for example OpenSSL gets bumped mid-cycle. Glen --M/v0iXgzSsdULkoO Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAEBCAAdFiEEjRJAPC5sqwhs9k2jAxRYpUeP4pMFAl0UJYkACgkQAxRYpUeP 4pOsUxAAmreejP4UNQFlu7IxoY95r70J056MBGr299u3MR1+eyL5DPE+kLDmNLck 8vwnMZbCXReP4bvzRJ1O9jW3hDphLm1ubHAc5m/Diym6okBc4uaeP7pugWP6q4vL VdpeEBu5edxQ0b77a3/x2ExgoDVaRr024mF7cFNkfBSJDhxSA5zF7HQSgmzF4QPG NWnt1WKpfqNjUzsdk6Cn+eHR4JGmoVNaDIDPf+bPcuW0/D3yvDFscx6frGi64zEk set/L2ruKYGCa4E1ivcABMG6+7VPh1Df+cGb++6hHuaJm9ANE/Tmi6n6ZHAleELN gF6HNgb8yznIWnDke7e7fdPf3shi5BCIk427+Qcx8PB/FlvAkUwV2lc3Ur3kpDRU HHFdOGmE+vm7Z5OYSywnDewgEW2iXYmvZgVPAzmH2slIXvDvvl+s32eCYRXSAWhe MrJY5MVbr4QoG+hWECEE534exydNFv20KA48hQulwRRHgybXZafaNo6TkjZkSihb xkFECtBmEfPaKgTJNRmmn0Y9MO+JJTy9nhS55BXPc4CHiP71+O6rQbCOEGewlouG 9Dr1ZyNv/zaQKWuoojtOB1QlAHailBeCPUzNHWT5pQhqoOiIgJZt3fZHEe1bLVm6 wXEI+XNMRFMTBToZmR7IFuUNbHhj7eJwAn1WP2eKQz5C7nuzOKw= =6Urf -----END PGP SIGNATURE----- --M/v0iXgzSsdULkoO--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20190627021017.GY13146>