Обсуждение: Re: pgsql: Doc: fill in "major enhancements" list in v13 release notes.
[ 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> 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> 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> 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 <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 <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