On 04/09/2016 07:37 PM, Tatsuo Ishii wrote:
But I still think it wouldn't move the patch any closer to committable
state, because what it really needs is review whether the catalog
definition makes sense, whether it should be more like pg_statistic,
and so on. Only then it makes sense to describe the catalog structure
in the SGML docs, I think. That's why I added some basic SGML docs for
CREATE/DROP/ALTER STATISTICS, which I expect to be rather stable, and
not the catalog and other low-level stuff (which is commented heavily
in the code anyway).

Without "user-level docs" (now I understand that the term means all
SGML docs for you), it is very hard to find a visible
characteristics/behavior of the patch. CREATE/DROP/ALTER STATISTICS
just defines a user interface, and does not help how it affects to
the planning. The READMEs do not help either.

In this case reviewing your code is something like reviewing a
program which has no specification.

I certainly agree that reviewing a patch without the context is hard. My intent was to provide such context / explanation in the READMEs, but perhaps I failed to do so with enough detail.

BTW when you say that READMEs do not help either, does that mean you consider READMEs unsuitable for this type of information in general, or that the current READMEs lack important information?

That's the reason why I said before below, but it was never
seriously considered.

I've considered it, but my plan was to have detailed READMEs, and then eventually distill that into something suitable for the SGML (perhaps without discussion of some implementation details). Maybe that's not the right approach.

FWIW providing the context is why I started working on a "paper" explaining both the motivation and implementation, including a bit of math and figures (which is what we don't have in READMEs or SGML). I haven't updated it recently, and it probably got buried in the thread, but perhaps this would be a better way to provide the context?


Tomas Vondra                  http://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:

Reply via email to