Thread: Adding since-version tags to the docs?
Hello,
I often find it pity that our docs are missing any information on since when a certain GUC setting, SQL-level command or function was introduced.
Clicking through the "this page in other versions" links at the top of a webpage does help, but you still need to do some guessing (binary search?) with the clicks. :-)
It would be nice if we could make a script that would parse the sgml files and for every symbol it finds it would add a tag like "Since version 9.x". Such a script could start by checking out REL9_0_STABLE and looking through all symbols it can find, tagging them "Since 9.0". Then it could commit the result, check out the next version branch and apply said commit (some manual effort to merge it might be required), and repeat the process, assuming all newly found symbols must be introduced in this new version.
That is for the lists, tabular representation might require adding a new column, I'm not sure what would be the best format.
After this process is done once, we can have a requirement that every newly introduced symbol/command be tagged manually by the patch author.
Do you think such approach will work? Is there interest in having this done?
--
Alex
31.08.2015 14:06, Shulgin, Oleksandr пишет:
I think that you're looking for Feature matrix.Hello,I often find it pity that our docs are missing any information on since when a certain GUC setting, SQL-level command or function was introduced.Clicking through the "this page in other versions" links at the top of a webpage does help, but you still need to do some guessing (binary search?) with the clicks. :-)It would be nice if we could make a script that would parse the sgml files and for every symbol it finds it would add a tag like "Since version 9.x". Such a script could start by checking out REL9_0_STABLE and looking through all symbols it can find, tagging them "Since 9.0". Then it could commit the result, check out the next version branch and apply said commit (some manual effort to merge it might be required), and repeat the process, assuming all newly found symbols must be introduced in this new version.That is for the lists, tabular representation might require adding a new column, I'm not sure what would be the best format.After this process is done once, we can have a requirement that every newly introduced symbol/command be tagged manually by the patch author.Do you think such approach will work? Is there interest in having this done?--Alex
-- Anastasia Lubennikova Postgres Professional: http://www.postgrespro.com The Russian Postgres Company
Hi, On 2015-08-31 13:06:04 +0200, Shulgin, Oleksandr wrote: > I often find it pity that our docs are missing any information on since > when a certain GUC setting, SQL-level command or function was introduced. Same here. Not sure how to display it without getting disturbing the 'flow' of the docs too much though. > It would be nice if we could make a script that would parse the sgml files > and for every symbol it finds it would add a tag like "Since version 9.x". > Such a script could start by checking out REL9_0_STABLE and looking through > all symbols it can find, tagging them "Since 9.0". Then it could commit > the result, check out the next version branch and apply said commit (some > manual effort to merge it might be required), and repeat the process, > assuming all newly found symbols must be introduced in this new version. I doubt that this can easily be done automatedly. But it'd be cool if so. Perhaps we could start doing it going forward? Greetings, Andres Freund
On Mon, Aug 31, 2015 at 3:17 PM, Anastasia Lubennikova <a.lubennikova@postgrespro.ru> wrote:
31.08.2015 14:06, Shulgin, Oleksandr пишет:I think that you're looking for Feature matrix.Hello,I often find it pity that our docs are missing any information on since when a certain GUC setting, SQL-level command or function was introduced.Clicking through the "this page in other versions" links at the top of a webpage does help, but you still need to do some guessing (binary search?) with the clicks. :-)It would be nice if we could make a script that would parse the sgml files and for every symbol it finds it would add a tag like "Since version 9.x". Such a script could start by checking out REL9_0_STABLE and looking through all symbols it can find, tagging them "Since 9.0". Then it could commit the result, check out the next version branch and apply said commit (some manual effort to merge it might be required), and repeat the process, assuming all newly found symbols must be introduced in this new version.That is for the lists, tabular representation might require adding a new column, I'm not sure what would be the best format.After this process is done once, we can have a requirement that every newly introduced symbol/command be tagged manually by the patch author.Do you think such approach will work? Is there interest in having this done?--Alex
Thanks, that might come handy sometime.
Though what I'm really up to is a direct statement in the documentation, like the Python stdlib docs do. I find it really helpful then you read about a command or a function you might want to use to know immediately that it was added in like 9.3 and you still have to support 9.1 in your code, things like that.
Actually, Python docs go further by providing distinct "New in version X.Y" and "Changed in version X.Y: ..." to describe behavior change when that does happen, like new parameters being added, etc. This we cannot extract automatically for sure, but I think such cases are rare enough and usually get a notice anyway.
--
Alex
On Mon, Aug 31, 2015 at 3:30 PM, Andres Freund <andres@anarazel.de> wrote:
Hi,
On 2015-08-31 13:06:04 +0200, Shulgin, Oleksandr wrote:
> I often find it pity that our docs are missing any information on since
> when a certain GUC setting, SQL-level command or function was introduced.
Same here. Not sure how to display it without getting disturbing the
'flow' of the docs too much though.
> It would be nice if we could make a script that would parse the sgml files
> and for every symbol it finds it would add a tag like "Since version 9.x".
> Such a script could start by checking out REL9_0_STABLE and looking through
> all symbols it can find, tagging them "Since 9.0". Then it could commit
> the result, check out the next version branch and apply said commit (some
> manual effort to merge it might be required), and repeat the process,
> assuming all newly found symbols must be introduced in this new version.
I doubt that this can easily be done automatedly. But it'd be cool if
so.
I'll try to see if that's feasible. :-)
Perhaps we could start doing it going forward?
I would be all for that.
--
Alex
"Shulgin, Oleksandr" <oleksandr.shulgin@zalando.de> writes:
> I often find it pity that our docs are missing any information on since
> when a certain GUC setting, SQL-level command or function was introduced.
> It would be nice if we could make a script that would parse the sgml files
> and for every symbol it finds it would add a tag like "Since version 9.x".
TBH, I think this is a horrid idea. We occasionally manually add remarks
like "since version x.y, Postgres does this". Inevitably, that just bulks
up the documentation; and it starts to look seriously silly in a few years
when x.y and all its predecessors are out of support. It'll be a real
mess if we do that for everything.
There might be a use-case for a table of this sort somewhere, but please
not in the main documentation.
regards, tom lane
On Mon, Aug 31, 2015 at 4:01 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
"Shulgin, Oleksandr" <oleksandr.shulgin@zalando.de> writes:
> I often find it pity that our docs are missing any information on since
> when a certain GUC setting, SQL-level command or function was introduced.
> It would be nice if we could make a script that would parse the sgml files
> and for every symbol it finds it would add a tag like "Since version 9.x".
TBH, I think this is a horrid idea. We occasionally manually add remarks
like "since version x.y, Postgres does this". Inevitably, that just bulks
up the documentation; and it starts to look seriously silly in a few years
when x.y and all its predecessors are out of support.
Well, I wouldn't name it outright silly: what's so bad about knowing that certain feature was there since 9.0, for example? I think can actually help then sending a docs link to someone who can read the docs, but not the code (or at least not that easily).
I would also find it more reassuring for myself to read it stated in the document rather than trying to track down a version where the feature did appear using git log --grep or the mentioned click-through technique for older versions. Can't speak for the others, of course.
It'll be a real
mess if we do that for everything.
I share the fear that it could become messy, but it doesn't necessary *have to* be a mess.
--
Alex
"Shulgin, Oleksandr" <oleksandr.shulgin@zalando.de> writes:
> On Mon, Aug 31, 2015 at 4:01 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> TBH, I think this is a horrid idea. We occasionally manually add remarks
>> like "since version x.y, Postgres does this". Inevitably, that just bulks
>> up the documentation; and it starts to look seriously silly in a few years
>> when x.y and all its predecessors are out of support.
> Well, I wouldn't name it outright silly: what's so bad about knowing that
> certain feature was there since 9.0, for example?
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.
regards, tom lane
On Mon, Aug 31, 2015 at 4:01 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:It'll be a real
mess if we do that for everything.I share the fear that it could become messy, but it doesn't necessary *have to* be a mess.
The extensions and SQL command sections are quite amenable to this kind of note - and also have the lesser need since those pages are already standalone and you can browse the versions at the top to figure out when the page was added. The function tables and, to a lesser extent, types are likely to find the greater benefit to this but are also most likely to have information overload.
I would be content with a policy that only version tags corresponding to active releases be included and that tags pointing to older releases be removed. If we are consistent with the corresponding tagging and wording the removal aspect can be fully automated.
I have interest in this but not enough to cobble together a patch containing a sufficient number of examples that the community can review and vote upon.
David J.
On 2015-08-31 10:48:01 -0400, Tom Lane wrote: > 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. If we add that information in sane way we should be able to remove it automatically after de-supporting old versions. Greetings, Andres Freund
On Mon, Aug 31, 2015 at 4:48 PM, Tom Lane <tgl@sss.pgh.pa.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.