public inbox for [email protected]
help / color / mirror / Atom feedLets prohibit predicting the future in the documentation.
9+ messages / 6 participants
[nested] [flat]
* Lets prohibit predicting the future in the documentation.
@ 2025-07-31 02:17 David G. Johnston <[email protected]>
2025-07-31 02:31 ` Re: Lets prohibit predicting the future in the documentation. David G. Johnston <[email protected]>
2025-07-31 03:03 ` Re: Lets prohibit predicting the future in the documentation. David Rowley <[email protected]>
0 siblings, 2 replies; 9+ messages in thread
From: David G. Johnston @ 2025-07-31 02:17 UTC (permalink / raw)
To: PostgreSQL Documentation <[email protected]>
Came across this again today...we added, way back in v11:
"This limitation will likely be removed in a future version of
<productname>PostgreSQL</productname>."
https://www.postgresql.org/docs/18/sql-createstatistics.html
David J.
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Lets prohibit predicting the future in the documentation.
2025-07-31 02:17 Lets prohibit predicting the future in the documentation. David G. Johnston <[email protected]>
@ 2025-07-31 02:31 ` David G. Johnston <[email protected]>
1 sibling, 0 replies; 9+ messages in thread
From: David G. Johnston @ 2025-07-31 02:31 UTC (permalink / raw)
To: PostgreSQL Documentation <[email protected]>
On Wed, Jul 30, 2025 at 7:17 PM David G. Johnston <
[email protected]> wrote:
> Came across this again today...we added, way back in v11:
>
> "This limitation will likely be removed in a future version of
> <productname>PostgreSQL</productname>."
>
>
Or, maybe phrase it: "Patches are welcomed."
David J.
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Lets prohibit predicting the future in the documentation.
2025-07-31 02:17 Lets prohibit predicting the future in the documentation. David G. Johnston <[email protected]>
@ 2025-07-31 03:03 ` David Rowley <[email protected]>
2025-07-31 10:05 ` Re: Lets prohibit predicting the future in the documentation. Magnus Hagander <[email protected]>
1 sibling, 1 reply; 9+ messages in thread
From: David Rowley @ 2025-07-31 03:03 UTC (permalink / raw)
To: David G. Johnston <[email protected]>; +Cc: PostgreSQL Documentation <[email protected]>
On Thu, 31 Jul 2025 at 14:17, David G. Johnston
<[email protected]> wrote:
>
> Came across this again today...we added, way back in v11:
>
> "This limitation will likely be removed in a future version of <productname>PostgreSQL</productname>."
>
> https://www.postgresql.org/docs/18/sql-createstatistics.html
This sort of thing doesn't particularly upset me. I don't believe we
should hide the fact that certain features might need more work. If it
inspires someone to work on making improvements, wouldn't it be
worthwhile keeping these? A huge amount of stuff gets done around here
because people find some inspiration to make things better. I don't
believe all those people need to experience the problems first-hand to
be able to fix them. Plenty of people arrive here just looking to get
involved and make a difference. I presume that something like this
being mentioned in the docs likely has a much better "we actually want
this feature" ratio than the TODO list does. I also imagine it's more
likely to inspire users of PostgreSQL to get involved in developing
than the TODO list is.
-1 from me.
David
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Lets prohibit predicting the future in the documentation.
2025-07-31 02:17 Lets prohibit predicting the future in the documentation. David G. Johnston <[email protected]>
2025-07-31 03:03 ` Re: Lets prohibit predicting the future in the documentation. David Rowley <[email protected]>
@ 2025-07-31 10:05 ` Magnus Hagander <[email protected]>
2025-07-31 23:23 ` Re: Lets prohibit predicting the future in the documentation. Peter Smith <[email protected]>
0 siblings, 1 reply; 9+ messages in thread
From: Magnus Hagander @ 2025-07-31 10:05 UTC (permalink / raw)
To: David Rowley <[email protected]>; +Cc: David G. Johnston <[email protected]>; PostgreSQL Documentation <[email protected]>
On Thu, Jul 31, 2025 at 5:03 AM David Rowley <[email protected]> wrote:
> On Thu, 31 Jul 2025 at 14:17, David G. Johnston
> <[email protected]> wrote:
> >
> > Came across this again today...we added, way back in v11:
> >
> > "This limitation will likely be removed in a future version of
> <productname>PostgreSQL</productname>."
> >
> > https://www.postgresql.org/docs/18/sql-createstatistics.html
>
> This sort of thing doesn't particularly upset me. I don't believe we
> should hide the fact that certain features might need more work. If it
> inspires someone to work on making improvements, wouldn't it be
> worthwhile keeping these? A huge amount of stuff gets done around here
> because people find some inspiration to make things better. I don't
> believe all those people need to experience the problems first-hand to
> be able to fix them. Plenty of people arrive here just looking to get
> involved and make a difference. I presume that something like this
> being mentioned in the docs likely has a much better "we actually want
> this feature" ratio than the TODO list does. I also imagine it's more
> likely to inspire users of PostgreSQL to get involved in developing
> than the TODO list is.
>
> -1 from me.
>
I can agree that the "will likely be removed" is a bad wording, and clearly
it was wrong :) 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.
--
Magnus Hagander
Me: https://www.hagander.net/ <http://www.hagander.net/;
Work: https://www.redpill-linpro.com/ <http://www.redpill-linpro.com/;
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Lets prohibit predicting the future in the documentation.
2025-07-31 02:17 Lets prohibit predicting the future in the documentation. David G. Johnston <[email protected]>
2025-07-31 03:03 ` Re: Lets prohibit predicting the future in the documentation. David Rowley <[email protected]>
2025-07-31 10:05 ` Re: Lets prohibit predicting the future in the documentation. Magnus Hagander <[email protected]>
@ 2025-07-31 23:23 ` Peter Smith <[email protected]>
2025-07-31 23:39 ` Re: Lets prohibit predicting the future in the documentation. David G. Johnston <[email protected]>
0 siblings, 1 reply; 9+ messages in thread
From: Peter Smith @ 2025-07-31 23:23 UTC (permalink / raw)
To: Magnus Hagander <[email protected]>; +Cc: David Rowley <[email protected]>; David G. Johnston <[email protected]>; PostgreSQL Documentation <[email protected]>
On Thu, Jul 31, 2025 at 8:05 PM Magnus Hagander <[email protected]> wrote:
>
>
>
> On Thu, Jul 31, 2025 at 5:03 AM David Rowley <[email protected]> wrote:
>>
>> On Thu, 31 Jul 2025 at 14:17, David G. Johnston
>> <[email protected]> wrote:
>> >
>> > Came across this again today...we added, way back in v11:
>> >
>> > "This limitation will likely be removed in a future version of <productname>PostgreSQL</productname>."
>> >
>> > https://www.postgresql.org/docs/18/sql-createstatistics.html
>>
>> This sort of thing doesn't particularly upset me. I don't believe we
>> should hide the fact that certain features might need more work. If it
>> inspires someone to work on making improvements, wouldn't it be
>> worthwhile keeping these? A huge amount of stuff gets done around here
>> because people find some inspiration to make things better. I don't
>> believe all those people need to experience the problems first-hand to
>> be able to fix them. Plenty of people arrive here just looking to get
>> involved and make a difference. I presume that something like this
>> being mentioned in the docs likely has a much better "we actually want
>> this feature" ratio than the TODO list does. I also imagine it's more
>> likely to inspire users of PostgreSQL to get involved in developing
>> than the TODO list is.
>>
>> -1 from me.
>
>
> I can agree that the "will likely be removed" is a bad wording, and clearly it was wrong :) 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.
>
FYI, there are quite a lot like this. Mostly the docs are worded using
"may/might/can" rather than "will" be changed.
Some examples (e.g. search .sgml for "future")
... but this may change in future releases.
... These will probably be fixed in future releases:
... An area for future development is to ...
... restriction that may be lifted in a future version ...
... this might be replaced by a different mechanism in the future.
... This may be changed in a future release ...
... might change in a future release.
... This information describes possible future behavior.
... some of these restrictions might be loosened in a future release.
... (this behavior might change in the future).
... These can and probably will be fixed in future releases:
... These deficiencies may be remedied in future versions ...
... It is hoped that a future version of this module will ...
... This restriction on ... may be lifted in a future version
... These might be addressed in future releases.
... This may be expanded in the future.
... might be changed in a future release.
... This is an implementation restriction that might be fixed in
future releases.
======
Kind Regards,
Peter Smith.
Fujitsu Australia
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Lets prohibit predicting the future in the documentation.
2025-07-31 02:17 Lets prohibit predicting the future in the documentation. David G. Johnston <[email protected]>
2025-07-31 03:03 ` Re: Lets prohibit predicting the future in the documentation. David Rowley <[email protected]>
2025-07-31 10:05 ` Re: Lets prohibit predicting the future in the documentation. Magnus Hagander <[email protected]>
2025-07-31 23:23 ` Re: Lets prohibit predicting the future in the documentation. Peter Smith <[email protected]>
@ 2025-07-31 23:39 ` David G. Johnston <[email protected]>
2025-08-04 11:22 ` Re: Lets prohibit predicting the future in the documentation. Álvaro Herrera <[email protected]>
0 siblings, 1 reply; 9+ messages in thread
From: David G. Johnston @ 2025-07-31 23:39 UTC (permalink / raw)
To: Peter Smith <[email protected]>; +Cc: Magnus Hagander <[email protected]>; David Rowley <[email protected]>; PostgreSQL Documentation <[email protected]>
On Thu, Jul 31, 2025 at 4:24 PM Peter Smith <[email protected]> wrote:
> On Thu, Jul 31, 2025 at 8:05 PM Magnus Hagander <[email protected]>
> wrote:
> >
> >
> >
> > On Thu, Jul 31, 2025 at 5:03 AM David Rowley <[email protected]>
> wrote:
> >>
> >> On Thu, 31 Jul 2025 at 14:17, David G. Johnston
> >> <[email protected]> wrote:
> >> >
> >> > Came across this again today...we added, way back in v11:
> >> >
> >> > "This limitation will likely be removed in a future version of
> <productname>PostgreSQL</productname>."
> >> >
> >> > https://www.postgresql.org/docs/18/sql-createstatistics.html
> >>
> >> This sort of thing doesn't particularly upset me. I don't believe we
> >> should hide the fact that certain features might need more work. If it
> >> inspires someone to work on making improvements, wouldn't it be
> >> worthwhile keeping these? A huge amount of stuff gets done around here
> >> because people find some inspiration to make things better. I don't
> >> believe all those people need to experience the problems first-hand to
> >> be able to fix them. Plenty of people arrive here just looking to get
> >> involved and make a difference. I presume that something like this
> >> being mentioned in the docs likely has a much better "we actually want
> >> this feature" ratio than the TODO list does. I also imagine it's more
> >> likely to inspire users of PostgreSQL to get involved in developing
> >> than the TODO list is.
> >>
> >> -1 from me.
> >
> >
> > I can agree that the "will likely be removed" is a bad wording, and
> clearly it was wrong :) 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.
> >
>
> FYI, there are quite a lot like this. Mostly the docs are worded using
> "may/might/can" rather than "will" be changed.
>
>
Yeah, I haven't been able to dig into the source yet on this topic but
basically that says to me that lots of people, with good intentions, want
to couch bad news (limitations) with something positive (hope). But in the
documentation it ends up almost inevitably turning into false hope.
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.
David J.
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Lets prohibit predicting the future in the documentation.
2025-07-31 02:17 Lets prohibit predicting the future in the documentation. David G. Johnston <[email protected]>
2025-07-31 03:03 ` Re: Lets prohibit predicting the future in the documentation. David Rowley <[email protected]>
2025-07-31 10:05 ` Re: Lets prohibit predicting the future in the documentation. Magnus Hagander <[email protected]>
2025-07-31 23:23 ` Re: Lets prohibit predicting the future in the documentation. Peter Smith <[email protected]>
2025-07-31 23:39 ` Re: Lets prohibit predicting the future in the documentation. David G. Johnston <[email protected]>
@ 2025-08-04 11:22 ` Álvaro Herrera <[email protected]>
2025-08-04 16:30 ` Re: Lets prohibit predicting the future in the documentation. David G. Johnston <[email protected]>
0 siblings, 1 reply; 9+ messages in thread
From: Álvaro Herrera @ 2025-08-04 11:22 UTC (permalink / raw)
To: David G. Johnston <[email protected]>; +Cc: Peter Smith <[email protected]>; Magnus Hagander <[email protected]>; David Rowley <[email protected]>; PostgreSQL Documentation <[email protected]>
On 2025-Jul-31, David G. Johnston wrote:
> > On Thu, Jul 31, 2025 at 8:05 PM Magnus Hagander <[email protected]>
> > 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/
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Lets prohibit predicting the future in the documentation.
2025-07-31 02:17 Lets prohibit predicting the future in the documentation. David G. Johnston <[email protected]>
2025-07-31 03:03 ` Re: Lets prohibit predicting the future in the documentation. David Rowley <[email protected]>
2025-07-31 10:05 ` Re: Lets prohibit predicting the future in the documentation. Magnus Hagander <[email protected]>
2025-07-31 23:23 ` Re: Lets prohibit predicting the future in the documentation. Peter Smith <[email protected]>
2025-07-31 23:39 ` Re: Lets prohibit predicting the future in the documentation. David G. Johnston <[email protected]>
2025-08-04 11:22 ` Re: Lets prohibit predicting the future in the documentation. Álvaro Herrera <[email protected]>
@ 2025-08-04 16:30 ` David G. Johnston <[email protected]>
2025-09-08 15:35 ` Re: Lets prohibit predicting the future in the documentation. Robert Haas <[email protected]>
0 siblings, 1 reply; 9+ messages in thread
From: David G. Johnston @ 2025-08-04 16:30 UTC (permalink / raw)
To: Álvaro Herrera <[email protected]>; +Cc: Peter Smith <[email protected]>; Magnus Hagander <[email protected]>; David Rowley <[email protected]>; PostgreSQL Documentation <[email protected]>
On Monday, August 4, 2025, Álvaro Herrera <[email protected]> wrote:
> On 2025-Jul-31, David G. Johnston wrote:
>
> > > On Thu, Jul 31, 2025 at 8:05 PM Magnus Hagander <[email protected]>
> > > 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.
I’m not saying it is wrong because it is impossible this will ever be
implemented. It’s wrong because after 7 years the probability of this being
removed are somewhere near 5% which is “unlikely”. Had it been truly
likely it would have been done within a few years at worse, IMO.
> 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?
I just don’t like giving out false hope. I’m unable to judge how much that
harms people in this situation though. And given how nitpicky we tend to
get on clarity and succinctness in other aspects of the documentation
having this seeming surpurflous and misleading sentence present seem to go
against the grain.
David J.
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Lets prohibit predicting the future in the documentation.
2025-07-31 02:17 Lets prohibit predicting the future in the documentation. David G. Johnston <[email protected]>
2025-07-31 03:03 ` Re: Lets prohibit predicting the future in the documentation. David Rowley <[email protected]>
2025-07-31 10:05 ` Re: Lets prohibit predicting the future in the documentation. Magnus Hagander <[email protected]>
2025-07-31 23:23 ` Re: Lets prohibit predicting the future in the documentation. Peter Smith <[email protected]>
2025-07-31 23:39 ` Re: Lets prohibit predicting the future in the documentation. David G. Johnston <[email protected]>
2025-08-04 11:22 ` Re: Lets prohibit predicting the future in the documentation. Álvaro Herrera <[email protected]>
2025-08-04 16:30 ` Re: Lets prohibit predicting the future in the documentation. David G. Johnston <[email protected]>
@ 2025-09-08 15:35 ` Robert Haas <[email protected]>
0 siblings, 0 replies; 9+ messages in thread
From: Robert Haas @ 2025-09-08 15:35 UTC (permalink / raw)
To: David G. Johnston <[email protected]>; +Cc: Álvaro Herrera <[email protected]>; Peter Smith <[email protected]>; Magnus Hagander <[email protected]>; David Rowley <[email protected]>; PostgreSQL Documentation <[email protected]>
On Mon, Aug 4, 2025 at 12:30 PM David G. Johnston
<[email protected]> wrote:
> I’m not saying it is wrong because it is impossible this will ever be implemented. It’s wrong because after 7 years the probability of this being removed are somewhere near 5% which is “unlikely”. Had it been truly likely it would have been done within a few years at worse, IMO.
I have mixed feelings about this particular example, but I agree that
it's best not to prognosticate about future feature development in the
docs, or even future deprecation. We're wrong A LOT when we do that.
It's best to just document what is and not what might be later.
--
Robert Haas
EDB: http://www.enterprisedb.com
^ permalink raw reply [nested|flat] 9+ messages in thread
end of thread, other threads:[~2025-09-08 15:35 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2025-07-31 02:17 Lets prohibit predicting the future in the documentation. David G. Johnston <[email protected]>
2025-07-31 02:31 ` David G. Johnston <[email protected]>
2025-07-31 03:03 ` David Rowley <[email protected]>
2025-07-31 10:05 ` Magnus Hagander <[email protected]>
2025-07-31 23:23 ` Peter Smith <[email protected]>
2025-07-31 23:39 ` David G. Johnston <[email protected]>
2025-08-04 11:22 ` Álvaro Herrera <[email protected]>
2025-08-04 16:30 ` David G. Johnston <[email protected]>
2025-09-08 15:35 ` Robert Haas <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox