Re: git: c4e48b65b7 - main - 13.1 relnotes: Change previous entries to avoid imperative.

Glen Barber <[email protected]> Wed, 13 Apr 2022 17:47:00 +0000

Newsgroups	gmane.os.freebsd.devel.cvs.doc
Message-ID	<[email protected]>

On Wed, Apr 13, 2022 at 12:37:31PM -0500, Mike Karels wrote:
> On 13 Apr 2022, at 12:12, Glen Barber wrote:
> 
> > On Wed, Apr 13, 2022 at 10:09:53AM -0700, John Baldwin wrote:
> >> On 4/12/22 6:33 PM, Mike Karels wrote:
> >>> The branch main has been updated by karels (src committer):
> >>>
> >>> URL: https://cgit.FreeBSD.org/doc/commit/?id=c4e48b65b76ff0ae15de17969d152233eeac83c4
> >>>
> >>> commit c4e48b65b76ff0ae15de17969d152233eeac83c4
> >>> Author:     Mike Karels <[email protected]>
> >>> AuthorDate: 2022-04-12 21:40:17 +0000
> >>> Commit:     Mike Karels <[email protected]>
> >>> CommitDate: 2022-04-13 01:32:44 +0000
> >>>
> >>>      13.1 relnotes: Change previous entries to avoid imperative.
> >>>      Change previous entries from "Add ..." to "... has been added",
> >>>      etc, for consistency.
> >>>      Reviewed by:    pauamma_gundo.com
> >>>      Differential Revision: https://reviews.freebsd.org/D34892
> >>
> >> Hmm, for 13.0 we explicitly used active voice rather than passive.  I don't know
> >> that we have a definitive style guide for release notes though.
> >>
> >
> > For the past few releases, I have been using "... had been added."
> > I personally have no complaint against using "... has been added."
> >

My apologies.  I had this reversed.  (See the 12.2-RELEASE notes for
example.)

> > I do not think we have a strict rule on this, one way or the other.
> 
> I checked the 13.0 version, and a lot of the entries are missing a subject,
> e.g. “Added ...” and “Removed ...”, which are not really sentences.  Some
> of the 13.1 entries could be changed to active voice, but I’m not sure what
> to use for a subject for “has been fixed”.
> 

I am inclined to think "[...] has been fixed", for example, referencing
the 12.2 release notes again:

% The ipfw(4) driver has been updated to support RFC6598/Carrier Grade
% NAT subnets.

In my opinion, "has been updated" and "has been fixed" are effectively
the same thing.

> I’m willing to make another pass if there is consensus.
> 

I think as long as we are consistent, there is no "right" or "wrong" way
to document release notes.  My $0.02 USD.

Glen

signature.asc (application/pgp-signature, 833 B)