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-874f5eaee...@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
