pgsql: Doc: fill in "major enhancements" list in v13 release notes.

On 9/10/20 1:14 PM, Tom Lane wrote:

Doc: fill in "major enhancements" list in v13 release notes.

Jonathan S. Katz, minor tweaks by me

Discussion: /messages/by-id/448a382b-ae07-3126-5a08-aacda9aa28ea@postgresql.org

Branch
------
REL_13_STABLE

Details
-------
https://git.postgresql.org/pg/commitdiff/3d92252d7d8bf7080ba61f1bda3d27bd8a3617e1

Modified Files
--------------
doc/src/sgml/release-13.sgml | 47 +++++++++++++++++++++++++++++++++-----------
1 file changed, 35 insertions(+), 12 deletions(-)

How is it that this commit still hasn't showed up on the web site, 4
days later? <https://www.postgresql.org/docs/13/release-13.html&gt; still
shows "TBD"

cheerds

andrew

--
Andrew Dunstan https://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

On Mon, Sep 14, 2020 at 3:28 PM Andrew Dunstan <
andrew.dunstan@2ndquadrant.com> wrote:

On 9/10/20 1:14 PM, Tom Lane wrote:

Doc: fill in "major enhancements" list in v13 release notes.

Jonathan S. Katz, minor tweaks by me

Discussion:

/messages/by-id/448a382b-ae07-3126-5a08-aacda9aa28ea@postgresql.org

Branch
------
REL_13_STABLE

Details
-------

https://git.postgresql.org/pg/commitdiff/3d92252d7d8bf7080ba61f1bda3d27bd8a3617e1

Modified Files
--------------
doc/src/sgml/release-13.sgml | 47

+++++++++++++++++++++++++++++++++-----------

1 file changed, 35 insertions(+), 12 deletions(-)

How is it that this commit still hasn't showed up on the web site, 4
days later? <https://www.postgresql.org/docs/13/release-13.html&gt; still
shows "TBD"

The "13" docs are only loaded along with releases, we don't load snapshot
versions into the docs other than the "devel" ones. That is, from a loading
perspective, 13 is treated the same as 12 or 11.

It becomes visible if you go to
https://www.postgresql.org/docs/13/index.html where it clearly says the
docs are from 13beta3.

So it'll get updated as soon as we load the RC docs.

--
Magnus Hagander
Me: https://www.hagander.net/ <http://www.hagander.net/&gt;
Work: https://www.redpill-linpro.com/ <http://www.redpill-linpro.com/&gt;

[ redirecting to -www ]

Magnus Hagander <magnus@hagander.net> writes:

On Mon, Sep 14, 2020 at 3:28 PM Andrew Dunstan <
andrew.dunstan@2ndquadrant.com> wrote:

How is it that this commit still hasn't showed up on the web site, 4
days later? <https://www.postgresql.org/docs/13/release-13.html&gt; still
shows "TBD"

The "13" docs are only loaded along with releases, we don't load snapshot
versions into the docs other than the "devel" ones. That is, from a loading
perspective, 13 is treated the same as 12 or 11.

Yeah, this is a downside of our decision to maintain release notes
per-branch. It used to be you could count on draft release notes to
show up in the website's devel docs fairly quickly; but now they
never appear there at all.

I've wondered if we could improve that. I agree with the policy that
the official docs copy should match the last official release ... but
maybe we could show unreleased release notes somewhere else, such as
under https://www.postgresql.org/docs/release/ ?

regards, tom lane

On 9/14/20 9:58 AM, Tom Lane wrote:

[ redirecting to -www ]

Magnus Hagander <magnus@hagander.net> writes:

On Mon, Sep 14, 2020 at 3:28 PM Andrew Dunstan <
andrew.dunstan@2ndquadrant.com> wrote:

How is it that this commit still hasn't showed up on the web site, 4
days later? <https://www.postgresql.org/docs/13/release-13.html&gt; still
shows "TBD"

The "13" docs are only loaded along with releases, we don't load snapshot
versions into the docs other than the "devel" ones. That is, from a loading
perspective, 13 is treated the same as 12 or 11.

Yeah, this is a downside of our decision to maintain release notes
per-branch. It used to be you could count on draft release notes to
show up in the website's devel docs fairly quickly; but now they
never appear there at all.

I've wondered if we could improve that. I agree with the policy that
the official docs copy should match the last official release ... but
maybe we could show unreleased release notes somewhere else, such as
under https://www.postgresql.org/docs/release/ ?

Like these?

https://www.postgresql.org/docs/devel/release-14.html

Based on how it currently works, we'd have to update the logic to
include the devel docs, but those don't appear to include much, per the
comments above.

Otherwise, we'd have to take a special snapshot of just the beta line
(which we might do in the buildfarm?), load those into the website, then
display it.

It's possible, but it's no free lunch as we'd have to change a few
things to accommodate that.

I guess the question is how useful would it be to have it? I haven't had
a chance to look into the numbers about the general traffic to the PG13
release notes and the traffic to the release notes page as well, so this
is purely qualitative at this point.

Jonathan

On Mon, Sep 14, 2020 at 4:10 PM Jonathan S. Katz <jkatz@postgresql.org>
wrote:

On 9/14/20 9:58 AM, Tom Lane wrote:

[ redirecting to -www ]

Magnus Hagander <magnus@hagander.net> writes:

On Mon, Sep 14, 2020 at 3:28 PM Andrew Dunstan <
andrew.dunstan@2ndquadrant.com> wrote:

How is it that this commit still hasn't showed up on the web site, 4
days later? <https://www.postgresql.org/docs/13/release-13.html&gt; still
shows "TBD"

The "13" docs are only loaded along with releases, we don't load

snapshot

versions into the docs other than the "devel" ones. That is, from a

loading

perspective, 13 is treated the same as 12 or 11.

Yeah, this is a downside of our decision to maintain release notes
per-branch. It used to be you could count on draft release notes to
show up in the website's devel docs fairly quickly; but now they
never appear there at all.

I've wondered if we could improve that. I agree with the policy that
the official docs copy should match the last official release ... but
maybe we could show unreleased release notes somewhere else, such as
under https://www.postgresql.org/docs/release/ ?

Like these?

https://www.postgresql.org/docs/devel/release-14.html

Based on how it currently works, we'd have to update the logic to
include the devel docs, but those don't appear to include much, per the
comments above.

Otherwise, we'd have to take a special snapshot of just the beta line
(which we might do in the buildfarm?), load those into the website, then
display it.

It's possible, but it's no free lunch as we'd have to change a few
things to accommodate that.

I guess the question is how useful would it be to have it? I haven't had
a chance to look into the numbers about the general traffic to the PG13
release notes and the traffic to the release notes page as well, so this
is purely qualitative at this point.

Isn't the release notes page based off the same documentation load as the
general pages? It's just a different way to view them? So unless we
actually load the v13 docs on a different schedule it won't actually help?

And if we do load the docs on a higher frequency for it, then why not load
the full docs? :)

I'm pretty sure we could make it load the docs for v13 for example at a
higher frequency, using existing setups. We would just have to manually
pick which branch(es) that would be and add it as part of the "major
release checklist" to remember to turn it *off* once v13 is actually
released. (Some weird things might happen during the time between stamping
v13 and actually releasing it though -- any docs changes in between those
would end up published and then unpublished, but that's hoipefully not a
big problem)

Given that we only have one branch that is in the state of "labeled a
stable branch but it's not really a stable branch yet", and only for a few
months in the year, it seems doing that manually might well be acceptable?

--
Magnus Hagander
Me: https://www.hagander.net/ <http://www.hagander.net/&gt;
Work: https://www.redpill-linpro.com/ <http://www.redpill-linpro.com/&gt;

Magnus Hagander <magnus@hagander.net> writes:

On 9/14/20 9:58 AM, Tom Lane wrote:

Yeah, this is a downside of our decision to maintain release notes
per-branch. It used to be you could count on draft release notes to
show up in the website's devel docs fairly quickly; but now they
never appear there at all.

I've wondered if we could improve that. I agree with the policy that
the official docs copy should match the last official release ... but
maybe we could show unreleased release notes somewhere else, such as
under https://www.postgresql.org/docs/release/ ?

Given that we only have one branch that is in the state of "labeled a
stable branch but it's not really a stable branch yet", and only for a few
months in the year, it seems doing that manually might well be acceptable?

There are actually two somewhat separate use-cases here:

* Draft release notes for a pending major release.
* Draft release notes for minor releases.

In both cases, Bruce or I push some notes into the git tree, but there
is noplace for potential reviewers to look at a built version of the
notes. Reviewers must either read the raw SGML or build the docs
themselves. The situation was better before the release notes branch
split, because you could look at the devel version of the docs.

I agree that this is not something we need to expend cycles on on any
regular basis. Personally I'd be happy to manually push a button
somewhere after committing a relnotes update. The real issue though
is where does this show up on the website? Since, by definition,
we're talking about unreleased documentation, I don't think it
should replace the normal docs for the relevant branch.

regards, tom lane

On Mon, Sep 14, 2020 at 4:29 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:

Magnus Hagander <magnus@hagander.net> writes:

On 9/14/20 9:58 AM, Tom Lane wrote:

Yeah, this is a downside of our decision to maintain release notes
per-branch. It used to be you could count on draft release notes to
show up in the website's devel docs fairly quickly; but now they
never appear there at all.

I've wondered if we could improve that. I agree with the policy that
the official docs copy should match the last official release ... but
maybe we could show unreleased release notes somewhere else, such as
under https://www.postgresql.org/docs/release/ ?

Given that we only have one branch that is in the state of "labeled a
stable branch but it's not really a stable branch yet", and only for a

few

months in the year, it seems doing that manually might well be

acceptable?

There are actually two somewhat separate use-cases here:

* Draft release notes for a pending major release.
* Draft release notes for minor releases.

In both cases, Bruce or I push some notes into the git tree, but there
is noplace for potential reviewers to look at a built version of the
notes. Reviewers must either read the raw SGML or build the docs
themselves. The situation was better before the release notes branch
split, because you could look at the devel version of the docs.

I agree that this is not something we need to expend cycles on on any
regular basis. Personally I'd be happy to manually push a button
somewhere after committing a relnotes update. The real issue though
is where does this show up on the website? Since, by definition,
we're talking about unreleased documentation, I don't think it
should replace the normal docs for the relevant branch.

Well the question is, does this really apply only to the release notes.
What about other changes that are made to the documentation in-between
releases?

Perhaps we actually want a complete separate docs-load, including back
branches, that just gets hidden away somewhere and smacked full of labels
that it's not a production set of documentation etc? That would then cover
both release notes and reviews of other docs backpatching.

--
Magnus Hagander
Me: https://www.hagander.net/ <http://www.hagander.net/&gt;
Work: https://www.redpill-linpro.com/ <http://www.redpill-linpro.com/&gt;

Magnus Hagander <magnus@hagander.net> writes:

Well the question is, does this really apply only to the release notes.
What about other changes that are made to the documentation in-between
releases?

Perhaps we actually want a complete separate docs-load, including back
branches, that just gets hidden away somewhere and smacked full of labels
that it's not a production set of documentation etc? That would then cover
both release notes and reviews of other docs backpatching.

Yeah, that's quite a plausible proposal.

regards, tom lane

On 9/14/20 11:25 AM, Tom Lane wrote:

Magnus Hagander <magnus@hagander.net> writes:

Well the question is, does this really apply only to the release notes.
What about other changes that are made to the documentation in-between
releases?
Perhaps we actually want a complete separate docs-load, including back
branches, that just gets hidden away somewhere and smacked full of labels
that it's not a production set of documentation etc? That would then cover
both release notes and reviews of other docs backpatching.

Yeah, that's quite a plausible proposal.

Seems fair.

cheers

andrew

--
Andrew Dunstan https://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

On 9/14/20 11:54 AM, Andrew Dunstan wrote:

On 9/14/20 11:25 AM, Tom Lane wrote:

Magnus Hagander <magnus@hagander.net> writes:

Well the question is, does this really apply only to the release notes.
What about other changes that are made to the documentation in-between
releases?
Perhaps we actually want a complete separate docs-load, including back
branches, that just gets hidden away somewhere and smacked full of labels
that it's not a production set of documentation etc? That would then cover
both release notes and reviews of other docs backpatching.

Yeah, that's quite a plausible proposal.

Seems fair.

For my 2¢ -- my use case is that I typically have to read the release
notes prior to an update announcement (nevermind major release) and turn
it into...an update announcement.

What I've done as of late is that I check out whatever the latest stable
branch is and build the docs locally using the HTML styles, and read
them that way. That seem to work fine. It adds about 2-3 minutes to my
workflow, but for the frequency at which I have to do that, it's not all
that painful.

Would going to a URL make it easier? Sure. Is it worth the effort we'd
likely put Magnus, and possibly myself, through to make it easier? I
don't know.

Jonathan

"Jonathan S. Katz" <jkatz@postgresql.org> writes:

Would going to a URL make it easier? Sure. Is it worth the effort we'd
likely put Magnus, and possibly myself, through to make it easier? I
don't know.

Certainly a fair question, and over time we'd be adding something to the
project's carbon footprint too. I won't cry too much if we don't do it;
I was just reacting to Andrew's evident desire for docs changes to show
up somewhere on the website.

regards, tom lane

On Mon, Sep 14, 2020 at 10:29:14AM -0400, Tom Lane wrote:

There are actually two somewhat separate use-cases here:

* Draft release notes for a pending major release.
* Draft release notes for minor releases.

In both cases, Bruce or I push some notes into the git tree, but there
is noplace for potential reviewers to look at a built version of the
notes. Reviewers must either read the raw SGML or build the docs
themselves. The situation was better before the release notes branch
split, because you could look at the devel version of the docs.

This is not an issue for me since we have not branched master when I am
working on the major release notes. By the time we branch master, I am
pretty much done.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.com

The usefulness of a cup is in its emptiness, Bruce Lee