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

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

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

Tom Lane-2
[ redirecting to -www ]

Magnus Hagander <[hidden email]> writes:
> On Mon, Sep 14, 2020 at 3:28 PM Andrew Dunstan <
> [hidden email]> 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> 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


Reply | Threaded
Open this post in threaded view
|

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

Jonathan S. Katz-3
On 9/14/20 9:58 AM, Tom Lane wrote:

> [ redirecting to -www ]
>
> Magnus Hagander <[hidden email]> writes:
>> On Mon, Sep 14, 2020 at 3:28 PM Andrew Dunstan <
>> [hidden email]> 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> 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


signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

Magnus Hagander-2


On Mon, Sep 14, 2020 at 4:10 PM Jonathan S. Katz <[hidden email]> wrote:
On 9/14/20 9:58 AM, Tom Lane wrote:
> [ redirecting to -www ]
>
> Magnus Hagander <[hidden email]> writes:
>> On Mon, Sep 14, 2020 at 3:28 PM Andrew Dunstan <
>> [hidden email]> 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> 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?

--
Reply | Threaded
Open this post in threaded view
|

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

Tom Lane-2
Magnus Hagander <[hidden email]> 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


Reply | Threaded
Open this post in threaded view
|

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

Magnus Hagander-2


On Mon, Sep 14, 2020 at 4:29 PM Tom Lane <[hidden email]> wrote:
Magnus Hagander <[hidden email]> 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.

--
Reply | Threaded
Open this post in threaded view
|

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

Tom Lane-2
Magnus Hagander <[hidden email]> 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


Reply | Threaded
Open this post in threaded view
|

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

Andrew Dunstan-8

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

> Magnus Hagander <[hidden email]> 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



Reply | Threaded
Open this post in threaded view
|

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

Jonathan S. Katz-3
On 9/14/20 11:54 AM, Andrew Dunstan wrote:

>
> On 9/14/20 11:25 AM, Tom Lane wrote:
>> Magnus Hagander <[hidden email]> 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


signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

Tom Lane-2
"Jonathan S. Katz" <[hidden email]> 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


Reply | Threaded
Open this post in threaded view
|

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

Bruce Momjian
In reply to this post by Tom Lane-2
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  <[hidden email]>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

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