Re: Documenting removal of nonnullvalue() and friends

On Wed, Oct 13, 2010 at 11:25 PM, Josh Kupershmidt <schmiddy(at)gmail(dot)com> wrote:
> On Wed, Oct 13, 2010 at 9:56 PM, Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
>> On Tue, Oct 12, 2010 at 9:05 PM, Josh Kupershmidt <schmiddy(at)gmail(dot)com> wrote:
>>> On Tue, Oct 12, 2010 at 1:03 PM, Josh Kupershmidt <schmiddy(at)gmail(dot)com> wrote:
>>>> Perhaps a mention of this change could be made in the 8.4 release notes?
>>>
>>> And here's a patch for the 8.4 release notes.
>>
>> It seems odd to change our release notes after the fact.  I don't
>> think we usually do that.
>
> Well, I do count 10 or so updates to release-8.4.sgml since its
> release date (2009-07-01). Granted, most of these are minor cleanups
> or to document further point releases.

As far as I'm aware they're all for further point releases or markup
adjustments. I'm not aware of a case where we've changed the
*content* of the release notes after the fact. I might be wrong, of
course.

>> I'm also not really sure that this is important enough to be worth
>> documenting.  It looks fairly self-explanatory.
>
> Oh well.
>
> Would anyone favor instead back-patching the documentation for the
> 8.3, 8.2, and 8.1 branches to include mentions of these
> previously-undocumented functions, instead? In
> <http://archives.postgresql.org/pgsql-docs/2004-08/msg00015.php>, Tom
> opined that they should be left undocumented, but I really don't agree
> with that.
>
> I almost concluded the original -novice poster was simply missing a
> user-defined function from her old database, since googling for
> "postgresql nonnullvalue" brought up nothing useful, and there was no
> mention of it in the (current) source code. It seems pretty harsh to
> me to intentionally not document these functions, even if they are
> obscure and not terribly useful.

Well, I certainly would have supported documenting them when they
existed, and release-noting them when they were removed, but I'm not
too sure how much value there is in doing it years after the fact. A
future Google search will probably find this thread, or that one.

Still, I don't think it would be unreasonable to add a note to the
prior-release documentation saying - hey, these functions exist. They
are for internal use only, and do not exist in later versions. Don't
use 'em. Now, how many people will actually see that note? Probably
not many. But it wouldn't bother me to have it there.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company