Date: Sun, 23 Jun 2019 21:57:29 +0000 From: Glen Barber <gjb@freebsd.org> To: Mark Johnston <markj@freebsd.org> Cc: Warner Losh <imp@bsdimp.com>, "freebsd-hackers@freebsd.org" <freebsd-hackers@freebsd.org>, FreeBSD Release Engineering Team <re@freebsd.org> Subject: Re: release notes file Message-ID: <20190623215729.GD41944@FreeBSD.org> In-Reply-To: <20190623210959.GB50070@raichu> References: <20190623191818.GA84365@raichu> <6B485E5C-9C8A-43C8-BD5A-528A74A61A23@FreeBSD.org> <79B7AEEE-7617-44D8-A16A-C8EC5F95455A@FreeBSD.org> <CANCZdfrvv9x3EyS=cgFQhKs6kNC9pnz5dnPziLbvYoyOT8UuZw@mail.gmail.com> <20190623201943.GB41944@FreeBSD.org> <20190623210959.GB50070@raichu>
next in thread | previous in thread | raw e-mail | index | archive | help
--ylS2wUBXLOxYXZFQ Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Sun, Jun 23, 2019 at 05:09:59PM -0400, Mark Johnston wrote: > On Sun, Jun 23, 2019 at 08:19:43PM +0000, Glen Barber wrote: > > On Sun, Jun 23, 2019 at 02:01:31PM -0600, Warner Losh wrote: > > > On Sun, Jun 23, 2019 at 1:56 PM Glen Barber <gjb@freebsd.org> wrote: > > >=20 > > > > FWIW, I don=E2=80=99t think =E2=80=9Ceither/or=E2=80=9D is necessar= ily the best approach; meaning > > > > I would like to still keep the tag in the default template. > > > > > > >=20 > > > A while ago, I proposed a protocol that we'd only have the RELNOTES f= ile. > > >=20 > > > The other part of the protocol was to remove it from RELNOTES once it= was > > > added to the release notes. This way, we can have multiple people wor= king > > > on the release notes should we be so fortunate to have those resource= s in > > > the future. It's minorly racy, but not terrible. This way, release no= tes > > > text could also be written by the committer and tweaked by whomever > > > compiles the release notes. > > >=20 > > > However, I'm cool with having it in the commit message + template sin= ce > > > it's better to have a heads up you need to write something than not. = The > > > understanding would be a RelNotes: yes would mean that someone else w= ould > > > write the notes and if you wanted to have more control over what went= out, > > > you'd use RELNOTES. > > >=20 > > > Glen, do you think that's a workable protocol? > > >=20 > >=20 > > It's kind of difficult for me to put the words together that effectively > > conveys what I'm thinking or where my mindset is here, but I'll try. > >=20 > > I am in full support of a RELNOTES file, but I think that should be > > supplementary to the 'Relnotes: yes' (or other variations of a non-empty > > tag). > >=20 > > I am conflicted on removing entries from a RELNOTES file once they are > > added to the release notes, because that might be a more convenient way > > for end users to get an idea of what changed. However, "Relnotes: yes" > > does not solve this for those folks. > >=20 > > It is easy to truncate the file when a new branch is created, just as > > a workflow example, but I think the larger thing here is that while > > there are folks that commit something without "Relnotes: yes" because > > they forgot (or it did not occur to them at the time that it is > > a user-visible change), it can be equally difficult to remember to > > update a file specifically dedicated to this. > >=20 > > All that said, having at least a sample text of what to include would be > > extremely helpful, at least for me, as sometimes I have to ping > > committers out-of-band to understand why a particular commit was flagged > > as "Relnotes: yes". > >=20 > > Hopefully all that made sense. :) >=20 > It makes sense to me. I think the idea is that "Relnotes: yes" is > advisory and serves as a reminder that the commit should get a release > note; committers may forget or not want to write RELNOTES entries for > some reason. Similar to how "MFC after" is advisory and doesn't > guarantee that an MFC has been done after any particular point. re@ > would need to scan commits for Relnotes tags that don't have entries in > RELNOTES. Since RELNOTES can be updated after the fact, this set > would hopefully be small. >=20 > Regarding whether RELNOTES entries should be removed, I would prefer to > keep them at least until head is branched. They would serve as useful > documentation to users, and if there are multiple people compiling > release notes they can synchronize in other ways. At least, I would > wait for it to become a problem before trying to solve it by removing > entries from RELNOTES. >=20 To your latter point, removing the RELNOTES entries, this is what I sort of had in mind: head -> stable/X -> releng/X.Y: head/RELNOTES gets truncated after stable/X is created; stable/X gets truncated after releng/X.Y is created For point releases, the workflow is similar as it just excludes head: stable/X -> releng/X.Y: stable/X gets truncated after releng/X.Y is created In other words, there would be no arbitrarily-long file, but there would potentially be some overlap for a major release where a dot-zero release has last-minute new stuff that should be in release notes; it would grow and shrink as development happens. Or, this is how I see it being most beneficial to RE when it comes to writing release notes, at least. Glen --ylS2wUBXLOxYXZFQ Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAEBCAAdFiEEjRJAPC5sqwhs9k2jAxRYpUeP4pMFAl0P9ckACgkQAxRYpUeP 4pN8oBAAiS8EWVfuFory2Qs1CSNNh+K0rLHM+CVt+g9eUDMlcLtsc7jdqA/Fz17L tFbXQVOupTTFVqsalTl/Q/luHT/m6zxLTypcO6nhRbI2bN01Hokls+4RAp8TVSmJ wMSpgmASjnccNeHVFjjYir0XOkK1uykaBZnFCFKrcwpLYefOa3lh8XQXRi08Emvs ICmv3neYXjWAas0xJXBeXEbPgpWRsY6OHVDAcaESrL9z12HVUKgl4FEVTlHGH1qx 8TTJBDCILiGcDZNLd6FRewTngTFHekILphwh247957kgZzepfYbpA8C0DVHWGd1m 6PMmApHuPRfp4QuZo0Q7wyPBnscgRKXReTfmyY3M9ck13FbLsgnEL1MQgB7M7Qnu dUnZPLCAbSPrQoYT30cT/tvgplr0AuZEfVQWR/0fhrPu/SEwWZESkUus6thsO8Xj 2lDvvoicwAKG922m/YQ3BuqFzJRceKxR4Ngh22VAMcyVha3PK5YIo9VZS3lB265t Un5cHbg9zsOEsAftTWlkKyd++aTKTPKpbhgTIqnOKYZ+rqqIYF8+xBrhDYdeuiAR /4TulD5SZx4NrVnVJrAVHZ46B/KQIOQV/Wy0egyz1zpqI2qisG3Itrv390ZAcHe/ 5kgHHLTRN3vRPWq9qiW2/H9W3jhjw7ZV0QJ7bIIyX+O+Gz5Nz+Y= =QgHd -----END PGP SIGNATURE----- --ylS2wUBXLOxYXZFQ--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20190623215729.GD41944>