Feedback-ID: ie3de48e3:Fastmail
Date: Mon, 4 Aug 2025 13:22:04 +0200
From: =?utf-8?Q?=C3=81lvaro?= Herrera <alvherre@kurilemu.de>
To: "David G. Johnston" <david.g.johnston@gmail.com>
Cc: Peter Smith <smithpb2250@gmail.com>,
	Magnus Hagander <magnus@hagander.net>, David Rowley <dgrowleyml@gmail.com>,
	PostgreSQL Documentation <pgsql-docs@lists.postgresql.org>
Subject: Re: Lets prohibit predicting the future in the documentation.
Message-ID: <202508041122.jvtae2whlxmu@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: 
 <CAKFQuwbfCk-bD_rbNbf9QURKw8p1n99YwZy+bhzcpH6nnWZ9_g@mail.gmail.com>
Archived-At: 
 <https://www.postgresql.org/message-id/202508041122.jvtae2whlxmu%40alvherre.pgsql>
Precedence: bulk

On 2025-Jul-31, David G. Johnston wrote:

> > On Thu, Jul 31, 2025 at 8:05 PM Magnus Hagander <magnus@hagander.net>
> > wrote:

> > > I can agree that the "will likely be removed" is a bad wording, and
> > > clearly it was wrong :)

I disagree that this was clearly wrong -- you just haven't seen that
future yet.  It doesn't say "it will be removed before Postgres 20" or
"it will be removed by 2025", or "it will be removed before David
Johnston comes across this documentation again".  It says "will be
removed in an unspecified future version", which seems sufficiently
open-ended to me.

> > > But something like "could be removed" would convey the important
> > > message that it is not a limitation of the concept itself, it's
> > > just something that hasn't been done yet -- and would perhaps
> > > encourage exactly the sort of thing yuo'r suggesting. Where as
> > > "will likely be removed" almost sounds like someone is already
> > > working on it.

We could change "will" to "might" or "may" or "could", but I think we
could also leave it well enough alone.  It doesn't actually hurt
anything, does it?

> There is no good way to extract all these "TODO" items from the HTML docs
> and seems like a non-optimal method for transferring knowledge to potential
> developers who may choose to try and remove such limitations.

You could add a bullet point to the TODO page in the wiki to complement
it, but I don't think you would remove the doc paragraph while it at;
instead it'd probably remain redundant until we actually implemented
extended stats on joins, and then we'd remove both.

-- 
Álvaro Herrera         PostgreSQL Developer  —  https://www.EnterpriseDB.com/