Re: Postgres 11 release notes

On 2018-07-09 16:52:11 +0200, David Fetter wrote:
> On Mon, Jul 09, 2018 at 10:36:30AM -0400, Bruce Momjian wrote:
> > On Sun, Jul  8, 2018 at 10:28:15PM -0700, Andres Freund wrote:
> > > On 2018-07-09 14:18:14 +0900, Tatsuro Yamada wrote:
> > > > Hi Bruce,
> > > > 
> > > > > I expect a torrent of feedback.;-)
> > > > 
> > > > Could you add this fix to the release note because this change affects
> > > > an extension developer using the hook function.
> > > > It would be better to know the change by reading the release note, not compilation error.
> > > > 
> > > > <!--
> > > > 2017-01-11 [4d41b2e09] Add QueryEnvironment to ExplainOneQuery_hook's parameter list.
> > > > -->
> > > >        <para>
> > > >         Add QueryEnvironment to ExplainOneQuery_hook's parameter list
> > > >         (Tatsuro Yamada, Thomas Munro)
> > > >        </para>
> > > > 
> > > > Discussion: https://postgr.es/m/890e8dd9-c1c7-a422-6892-874f5eaee048@lab.ntt.co.jp
> > > > 
> > > > I guess "E.1.3.11. Source Code" or "E.1.3.12. Additional Modules" sections are
> > > > suitable for putting the message in the release note.
> > > 
> > > We adapt plenty of functions signatures without listing them
> > > individually in the release notes. I don't think randomly selecting one
> > > relatively uncommonly used hook is a good way to attack that.
> > 
> > Agreed.  Ideally we would have a wiki page that lists _all_ the hooks,
> > and what release they were added.
> 
> If we're talking about ideals, all our public APIs including the hooks
> should be in the official documentation and have man pages.

FWIW, at this point in time I'd pretty strenuously object to a rule
requiring all hooks / all public functions to be documented. I think the
development velocity penalty would be far greater than the benefit.

That's however *NOT* to say, that we shouldn't document individual API
that we expect to be somewhat stable / frequently externally used (say
the PL interface, C trigger interface).

Greetings,

Andres Freund