From: Stephen Frost <sfrost@snowman.net>
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: Dave Cramer <davecramer@postgres.rocks>
Cc: Bruce Momjian <bruce@momjian.us>
Cc: David G. Johnston <david.g.johnston@gmail.com>
Cc: mali_86@outlook.com, Pg Docs <pgsql-docs@lists.postgresql.org>
Subject: Re: psql's commit df9f599b is not documented
Date: Tue, 3 Aug 2021 10:56:24 -0400
Message-ID: <20210803145624.GV20766@tamriel.snowman.net> (raw)
In-Reply-To: <1703967.1627999513@sss.pgh.pa.us>
References: <162794046650.25749.16629649309696437240@wrigleys.postgresql.org>
<CAKFQuwYddkFFAojWojCLjKb8Uq-BEXfX3O6fCPYOAB4SLtn20A@mail.gmail.com>
<20210802230959.GA7858@momjian.us>
<CAKFQuwYS2H1Q6wwy33G+aERP5Y58kMeiZ0x9TpCx=qDN=KvROw@mail.gmail.com>
<20210803000350.GA3639@momjian.us>
<CAKFQuwZjzhj2THbxKueK6g7V2_1n7xCkSxB2AbUpJTNXFiL1HA@mail.gmail.com>
<20210803005602.GB3639@momjian.us>
<CADK3HHLQCAKp+jHM2r5e_wigpyPBE+ineuVNYdj3qdziVMvkGw@mail.gmail.com>
<1703967.1627999513@sss.pgh.pa.us>
Greetings,
* Tom Lane (tgl@sss.pgh.pa.us) wrote:
> Dave Cramer <davecramer@postgres.rocks> writes:
> > I would agree. If it's worth coding it's worth documenting. Unless of
> > course the intention is that this is temporary.
>
> Documenting it would mean committing to keeping it indefinitely,
> which I think was exactly what people didn't want to do. It's
> a kluge and we might find ourselves backed into a situation where
> we have to take it out.
Given that it's been a while since 11 came out, this argument doesn't
seem like it really holds much water.
> > Do we have other undocumented features ?
>
> Yup. There are plenty of behaviors that are explained in code comments
> but not anywhere user-visible. If we tried to document absolutely
> everything that someone might be curious about, the manual would be
> three times its current size, but not more useful.
This isn't a deep internal behavior that we're talking about, it's a
very user-visible feature and now we're having users discover it and
then complain that it's not documented. I tend to agree with the
original poster and some others on this thread that it probably should
be documented.
Across major versions, if we feel the need to for whatever reason, we
can take it out even when it's documented. We've certainly done so for
other things in the past, I don't see why this should be viewed as
special in that regard.
Thanks,
Stephen
Attachments:
[application/pgp-signature] signature.asc (818B, ../20210803145624.GV20766@tamriel.snowman.net/2-signature.asc)
download
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: sfrost@snowman.net, tgl@sss.pgh.pa.us, davecramer@postgres.rocks, bruce@momjian.us, david.g.johnston@gmail.com, pgsql-docs@lists.postgresql.org
Subject: Re: psql's commit df9f599b is not documented
In-Reply-To: <20210803145624.GV20766@tamriel.snowman.net>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox