Date: Thu, 14 May 2020 07:23:05 +0200 (CEST)
From: Fabien COELHO <coelho@cri.ensmp.fr>
To: Bruce Momjian <bruce@momjian.us>
cc: Tom Lane <tgl@sss.pgh.pa.us>, Alvaro Herrera <alvherre@2ndquadrant.com>,
    PostgreSQL-development <pgsql-hackers@postgresql.org>
Subject: Re: PG 13 release notes, first draft
In-Reply-To: <20200513152202.GB20111@momjian.us>
Message-ID: <alpine.DEB.2.22.394.2005140701100.3685465@pseudo>
References: <20200512001744.GH4666@momjian.us>
 <20200512003456.GA29166@alvherre.pgsql> <20200512005714.GN4666@momjian.us>
 <11843.1589250233@sss.pgh.pa.us> <20200512025910.GX4666@momjian.us>
 <alpine.DEB.2.22.394.2005120943030.2831675@pseudo>
 <20200512211543.GB4666@momjian.us>
 <alpine.DEB.2.22.394.2005130707170.3283649@pseudo>
 <20200513152202.GB20111@momjian.us>
User-Agent: Alpine 2.22 (DEB 394 2020-01-19)
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII; format=flowed
Precedence: bulk


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.

>>>>  * 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.

>> 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.

-- 
Fabien.