Re: Adding since-version tags to the docs?

From: Catalin Iacob <iacobcatalin(at)gmail(dot)com>
To: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>
Cc: "Shulgin, Oleksandr" <oleksandr(dot)shulgin(at)zalando(dot)de>, PostgreSQL Hackers <pgsql-hackers(at)postgresql(dot)org>
Subject: Re: Adding since-version tags to the docs?
Date: 2015-09-01 18:20:51
Message-ID: CAHg_5gqwGUHMpxp=-wmyDhqHphN44_xb7qsux5+OxuZrk6TQ2Q@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

On Mon, Aug 31, 2015 at 4:48 PM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> Right now, you might well care about whether a feature arrived in 9.3 vs
> 9.4, for instance; but it's highly unlikely that you care whether a
> feature arrived in 7.1 or 7.2. The problem with this proposal is that
> it will add far more bloat of the latter sort than currently-useful
> information; and the ratio will get worse over time.

After working with Python, when reading the Postgres docs I did feel
this was missing so +1 from a user. An example for Python's
annotations is at https://docs.python.org/3/library/zipfile.html.
Python only keeps the annotations for a few versions back (3 or 4 I
think).

Another use case which is maybe worth mentioning explicitly: when I
needed to target a certain older version of Python, as long as it was
reasonably close to the current one, I would still read the latest
Python docs and rely on the version annotations to let me know I can't
yet use certain features. For Postgres, that doesn't feel "safe" so
you tend to go to the docs of the specific version you're targeting.
But by doing that, you miss getting extra education about improvements
in newer versions. That extra information could also be a powerful
trigger to update in order to gain those improvements. I think both
are quite valuable.

In response to

Browse pgsql-hackers by date

  From Date Subject
Next Message Andres Freund 2015-09-01 18:22:49 Re: Horizontal scalability/sharding
Previous Message Andres Freund 2015-09-01 18:12:22 Re: Proposal: Implement failover on libpq connect level.