Date: Tue, 3 Aug 2021 10:56:24 -0400
From: Stephen Frost <sfrost@snowman.net>
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: Dave Cramer <davecramer@postgres.rocks>,
	Bruce Momjian <bruce@momjian.us>,
	"David G. Johnston" <david.g.johnston@gmail.com>,
	mali_86@outlook.com, Pg Docs <pgsql-docs@lists.postgresql.org>
Subject: Re: psql's commit df9f599b is not documented
Message-ID: <20210803145624.GV20766@tamriel.snowman.net>
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>
MIME-Version: 1.0
Content-Type: multipart/signed; micalg=pgp-sha512;
	protocol="application/pgp-signature"; boundary="8UZM8vFmYU6qSNhq"
Content-Disposition: inline
In-Reply-To: <1703967.1627999513@sss.pgh.pa.us>
User-Agent: Mutt/1.5.24 (2015-08-30)
Archived-At: 
 <https://www.postgresql.org/message-id/20210803145624.GV20766%40tamriel.snowman.net>
Precedence: bulk


--8UZM8vFmYU6qSNhq
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

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.
>=20
> 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 ?
>=20
> 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

--8UZM8vFmYU6qSNhq
Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1

iQIcBAEBCgAGBQJhCVkYAAoJEO1sijiDR2RVtacP/3W1HZoP/s/su4dFZJQQkxAj
rzI0VqJ8zRkO0LMHHnaQ/WXwssF+36IynwUC6YC/MsOb1lT3I/mFZ42c+Wa1FRB9
xV8C8WGS8tOBAPdanffj8o/TVVUHO2oekDMtrkfvDQYtX0LbPglMozhhZ6c6N62u
f93hUG6HC2Cjw46wVV7A7auHflnzwXoZBvT0n2s1NNVVMmJ1JfVy88qEe3KrSOeh
eWf9y9dnmmhNZo2YWzx+jLr12vacr4AfAx6W65IScF1jtW/T/vwhPG81hNwK1dXk
t0FpYqgGN5PiIeO/BfEI8iX0p2WfRa3vsOBEyL1b8V+eoi9keLaD+qFyEImDNYNq
tw94kZJb58Rca2gu9Sk2cXvPnYFFV1gIc5vr9mC3wkXIMf8XZ2pJvb2gsQqEreIz
MQIhkfh39/8qDrG+jfaV9eGEMRJXp0/UUwL+/njPeZzYgonk5gA1o1PpqlMzu6OF
eQjOKAl/ONALD56mt4dqhz3w7B77rh7o/76Y3FdGy3lECm7rnHbUjKQ3M3IkKx21
UdrqBiXgaBCVTdLlmFBc+FfGN/CnI+NKwxbr9v3GBIFmZHNk41iWRZT+z1fBqMzn
LG3PERO9qGkWh2WVEAFxWqOqO6+1L5OC+mULi1PJre5RHrvksUnwT1IZVWCk4t0d
KBwlui1Bbu+YPOQgsqHs
=7b1T
-----END PGP SIGNATURE-----

--8UZM8vFmYU6qSNhq--