Re: PG 13 release notes, first draft - Mailing list pgsql-hackers

On Thu, May 14, 2020 at 07:23:05AM +0200, Fabien COELHO wrote:
> 
> Hello Bruce,
> 
> > > > >  * 34a0a81bfb
> > > > 
> > > > We already have:
> > > > 
> > > >     Reformat tables containing function information for better
> > > >     clarity (Tom Lane)
> > > > 
> > > > so it seems it is covered as part of this.
> > > 
> > > AFAICR this one is not by the same author, and although the point was about
> > > better clarity, it was not about formating but rather about restructuring
> > > text vs binary string function documentations. Then Tom reformatted the
> > > result.
> > 
> > Well, we were not even clear we should document changes in the functions
> > section, so going into details of all the changes seems unwise.
> 
> The restructuring was a significant change, and ISTM that another function
> of the release note is also to implicitely thank contributors (their name is
> appended, which does not bring any useful information about the feature from
> a release note perspective) hence my suggestion to include this one,
> the author of which is not Tom Lane.

We list people's names next to items.  We don't list items to list
people's names, as far as I know of the policy.  If you want to change
that, you will need to start a new thread and get agreement.

> > > > >  * e829337d42
> > > > 
> > > > Uh, this is a doc link formatting addition.  I think this falls into the
> > > > error message logic, where it is nice when people want it, but they
> > > > don't need to know about it ahead of time.
> > > 
> > > [...]
> > 
> > I don't see it.
> 
> While reading again the sequence, ISTM that I did not understand your first
> answer, so my answer was kind-of off topic, sorry. This is indeed "link
> formatting addition", which helps making the libpq doc more usable.

> Probably you do not need to know about it in advance, but I do not think
> that it is a good reason not to include it: with the same argument, a
> performance improvement would not need to be advertise, you'll see it when
> you need it. The same holds for all non-functional improvements, and there
> are many which are listed.

Peformance items are listed only if they will produce a visible change
in performance, or enable new workloads that were too slow in the past.

> > > Possibly, but as the "THIS WAS NOT DOCUMENTED BEFORE?" question seemed to
> > > still be in the release notes, I gathered that the information had not
> > > reached its destination, hence the possible repetition. But maybe the issue
> > > is that this answer is not satisfactory. Sorry for the inconvenience.
> > 
> > I removed it already based on feedback from someone else.
> 
> Good. I looked at the online version which is off the latest commits by a
> few hours.
> 
> I'd consider moving "Upgrade to use DocBook 4.5 (Peter Eisentraut)" to the
> doc section, maybe.

Agreed, done.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +