On Thu, 11 Feb 2010, Robert Haas wrote:
> On Thu, Feb 11, 2010 at 3:00 AM, Oleg Bartunov <oleg@sai.msu.su> wrote:
>>> version I saw hadn't any documentation whatever. It's not committable
>>> on documentation grounds alone, even if everybody was satisfied about
>>> the code.
>>
>> well, there is enough documentation to review patch.
>
> Where is there any documentation at all? There are no changes to doc/
> at all; no README; and not even a lengthy comment block anywhere that
> I saw. Nor did the email in which the patch was submitted clearly lay
> out the design of the feature.
Well, initial knngist announce
http://archives.postgresql.org/pgsql-hackers/2009-11/msg01547.php
isn't enough to review ? We made test data available to reproduce
results, see http://www.sai.msu.su/~megera/wiki/2009-11-25
We are here and open to any reviewer's question.
>
>> In my understanding
>> this was always enough to submit code. User's documentation is depend on
>> discussion and review and can be added later
>> before releasing beta.
>
> Several people have said this lately, but it doesn't match what I've
> seen of our practice over the last year and a half; Tom regularly
> boots patches that lack documentation (or necessary regression test
> updates). Sure, people often submit small patches without
> documentation thinking to fill it in later, but anything major pretty
> much has to have it, AFAICS. From my own point of view, I would never
> commit anything that lacked documentation, for fear of being asked to
> write it myself if the patch author didn't. Of course it's a bit
> different for committers, who can presumably be counted on to clean up
> their own mess, but I still think it's fair to expect at least some
> effort to be put into the docs before commit.
I think nobody will spend his time to write sgml code for user's
documentation for fear his patch will be rejected/moved/getting rewritten,
so his time will be just wasted.
Regards, Oleg
_____________________________________________________________
Oleg Bartunov, Research Scientist, Head of AstroNet (www.astronet.ru),
Sternberg Astronomical Institute, Moscow University, Russia
Internet: oleg@sai.msu.su, http://www.sai.msu.su/~megera/
phone: +007(495)939-16-83, +007(495)939-23-83