Thread: links to 12 release notes broken after branching
Hi, https://www.postgresql.org/docs/devel/release-12.html now isn't reachable, but for a while was the only URL we were able to hand out. Greetings, Andres Freund
On 9/17/19 11:53 AM, Andres Freund wrote: > Hi, > > https://www.postgresql.org/docs/devel/release-12.html now isn't > reachable, but for a while was the only URL we were able to hand out. https://www.postgresql.org/docs/12/release-12.html works fine now. There were a few places on the site that did not have this reference. For next year, when PG 13 Beta 1 is out, I'll be sure to just reference /docs/13/release-13.html on all web material. Thanks, Jonathan
Attachment
Hi, On 2019-09-17 11:55:01 -0400, Jonathan S. Katz wrote: > On 9/17/19 11:53 AM, Andres Freund wrote: > > Hi, > > > > https://www.postgresql.org/docs/devel/release-12.html now isn't > > reachable, but for a while was the only URL we were able to hand out. > > https://www.postgresql.org/docs/12/release-12.html works fine now. There > were a few places on the site that did not have this reference. Yes, but before the release being done we can't hand that out? So I don't think that's sufficient. Can't we have a rule that redirects to devel/release-NN.html to /NN/release-NN.html upon a 404? Greetings, Andres Freund
Andres Freund <andres@anarazel.de> writes:
> Yes, but before the release being done we can't hand that out? So I
> don't think that's sufficient. Can't we have a rule that redirects to
> devel/release-NN.html to /NN/release-NN.html upon a 404?
That seems like it'd cause everlasting confusion about which
branch links were really meant to point at.
I'd rather see us instantiate a new release branch under
www.postgresql.org/docs/ as soon as there's a good reason to
point to it, like around beta1, or maybe when we fork the
branch in git.
regards, tom lane
Hi, On 2019-09-17 13:04:11 -0400, Tom Lane wrote: > Andres Freund <andres@anarazel.de> writes: > > Yes, but before the release being done we can't hand that out? So I > > don't think that's sufficient. Can't we have a rule that redirects to > > devel/release-NN.html to /NN/release-NN.html upon a 404? > > That seems like it'd cause everlasting confusion about which > branch links were really meant to point at. Howso? There'll only be one release-NN file across all branches? Leaving aside the time where docs are regenerated etc? Greetings, Andres Freund
On 9/17/19 1:04 PM, Tom Lane wrote: > Andres Freund <andres@anarazel.de> writes: >> Yes, but before the release being done we can't hand that out? You can always hand them out knowing that it is subject to change. Personally I view devel as "anything can change at a given moment". I'll own up to my own mistake for linking to devel from someone of the emails/press releases around the PG12 lifecycle where I did not appropriately change the templates. I'll be sure not to do that for PG13. > So I >> don't think that's sufficient. Can't we have a rule that redirects to >> devel/release-NN.html to /NN/release-NN.html upon a 404? > > That seems like it'd cause everlasting confusion about which > branch links were really meant to point at. I did a quick look at the pgweb code to see what it would take. Coupled with the other changes we made to how we handle release notes, it's not so much a "redirect" as it is a "messy logic check that leads to a redirect. If need be I can make a quantifiable analysis of how many users this is actually impacting to see if it's worth introducing aforementioned logic, but preferably some time after PG12 is out the door. > I'd rather see us instantiate a new release branch under > www.postgresql.org/docs/ as soon as there's a good reason to > point to it, like around beta1, or maybe when we fork the > branch in git. beta1 is when "/docs/NN/" goes live anyway, so +1 by default from me :) Jonathan
Attachment
Hi, On 2019-09-17 13:50:40 -0400, Jonathan S. Katz wrote: > On 9/17/19 1:04 PM, Tom Lane wrote: > > Andres Freund <andres@anarazel.de> writes: > >> Yes, but before the release being done we can't hand that out? > > You can always hand them out knowing that it is subject to change. > Personally I view devel as "anything can change at a given moment". It still baffles me that that's supposed to be a reasonable approach. I mean, for quite a few weeks that's the only link available. And we want people to be able to look at the notes at that time. And expecting URLs to stay halfway stable isn't a novel or absurd thing in any sort of way. I think the whole project of pruning the release notes was done hastily and carelessly. At a much larger scope than necessarily apparent from the mailing list discussions. Greetings, Andres Freund
On 10/30/19 5:47 PM, Andres Freund wrote: > Hi, > > On 2019-09-17 13:50:40 -0400, Jonathan S. Katz wrote: >> On 9/17/19 1:04 PM, Tom Lane wrote: >>> Andres Freund <andres@anarazel.de> writes: >>>> Yes, but before the release being done we can't hand that out? >> >> You can always hand them out knowing that it is subject to change. >> Personally I view devel as "anything can change at a given moment". > > It still baffles me that that's supposed to be a reasonable approach. Why? "devel" is unstable by design. Let's say we add a new feature, and the page is at /docs/devel/a/newfeature.html Some discussion ensues on the mailing list, and we decide that it's better to put the documentation in /docs/devel/b/newfeature.html Suddenly, all old links to /docs/devel/a/newfeature.html break. Could we add a redirect for it? Sure, but why would we account for every possible permutation when we know that devel in itself is unstable? > I > mean, for quite a few weeks that's the only link available. And we want > people to be able to look at the notes at that time. And expecting URLs > to stay halfway stable isn't a novel or absurd thing in any sort of way. > > I think the whole project of pruning the release notes was done hastily > and carelessly. At a much larger scope than necessarily apparent from > the mailing list discussions. What would you suggest we do? To kick off possible solutions, perhaps the policy is we keep the "/docs/devel/release-13.html" around in "master" after the REL_13_STABLE branch is created. We keep that around until the time that 13.0 comes out, and then it is removed to make way for release-14.html Does that work? What is the overhead of maintaining that in core? I don't think this would be too painful in pgweb -- if I read the code correct, this may even be a no-op. Thanks, Jonathan
Hi, On 2019-10-30 17:59:16 -0400, Jonathan S. Katz wrote: > On 10/30/19 5:47 PM, Andres Freund wrote: > > Hi, > > > > On 2019-09-17 13:50:40 -0400, Jonathan S. Katz wrote: > >> On 9/17/19 1:04 PM, Tom Lane wrote: > >>> Andres Freund <andres@anarazel.de> writes: > >>>> Yes, but before the release being done we can't hand that out? > >> > >> You can always hand them out knowing that it is subject to change. > >> Personally I view devel as "anything can change at a given moment". > > > > It still baffles me that that's supposed to be a reasonable approach. > > Why? "devel" is unstable by design. I don't really buy this. Nor has it historically been true. > Let's say we add a new feature, and the page is at > /docs/devel/a/newfeature.html > > Some discussion ensues on the mailing list, and we decide that it's > better to put the documentation in /docs/devel/b/newfeature.html > > Suddenly, all old links to /docs/devel/a/newfeature.html break. > Could we add a redirect for it? Sure, but why would we account for every > possible permutation when we know that devel in itself is unstable? No, we shouldn't. I fail to see how a rare scenario about a renamed feature is analogous to being unable to persistently link to the release notes of an upcoming release. Note that the feature renaming exists between different branches too, and while it has created a complaint or two, it's pretty rare. > > I > > mean, for quite a few weeks that's the only link available. And we want > > people to be able to look at the notes at that time. And expecting URLs > > to stay halfway stable isn't a novel or absurd thing in any sort of way. > > > > I think the whole project of pruning the release notes was done hastily > > and carelessly. At a much larger scope than necessarily apparent from > > the mailing list discussions. > > What would you suggest we do? I think the ship has largely sailed. Not do things like this again, I guess. > To kick off possible solutions, perhaps the policy is we keep the > "/docs/devel/release-13.html" around in "master" after the > REL_13_STABLE branch is created. I don't understand why the obvious solution isn't to have docs/devel/release-NN.html link to docs/NN/release-NN.html upon miss, even while NN is not yet stable. That's a lot easier than unnecessarily keeping files around, and works permanently. You said before that it looks hairy to do so, but looking at https://git.postgresql.org/gitweb/?p=pgweb.git;a=blob;f=pgweb/docs/views.py;h=1480903cf82229461b9e909c9829e8ad9aff87b7;hb=HEAD it looks like all that's needed is allowing version specific redirects after branching/betas/rc, but before the release? As far as I can tell the current situation is that devel/release-NN.html links 1) work if NN hasn't yet branched off 2) stop working once NN has has branched, and release-NN.sgml is removed from master, because 83 is_released = Version.objects.filter(tree=release_version, testing=0).exists() if version == "devel" else True returns false, due to the testing = 0 check, which in turn means: 86 if is_released and release_version != ver: will not trigger a redirect yet. Which means we'll get a 404. 3) starts working again once NN is "fully" released because now is_released is true isn't all that's needed to rename is_released to exists_as_branch, and remove the testing=0 condition? > We keep that around until the time that 13.0 comes out, and then it is > removed to make way for release-14.html > > Does that work? What is the overhead of maintaining that in core? Definitely non-zero and ongoing due to minor release notes. Or confusing, bdecause it'll be outdated. Greetings, Andres Freund
On 10/30/19 6:26 PM, Andres Freund wrote: > Hi, > > On 2019-10-30 17:59:16 -0400, Jonathan S. Katz wrote: >> On 10/30/19 5:47 PM, Andres Freund wrote: >>> Hi, >>> >>> On 2019-09-17 13:50:40 -0400, Jonathan S. Katz wrote: >>>> On 9/17/19 1:04 PM, Tom Lane wrote: >>>>> Andres Freund <andres@anarazel.de> writes: >>>>>> Yes, but before the release being done we can't hand that out? >>>> >>>> You can always hand them out knowing that it is subject to change. >>>> Personally I view devel as "anything can change at a given moment". >>> >>> It still baffles me that that's supposed to be a reasonable approach. >> >> Why? "devel" is unstable by design. > > I don't really buy this. Nor has it historically been true. I'll stop selling it then ;) > >>> I >>> mean, for quite a few weeks that's the only link available. And we want >>> people to be able to look at the notes at that time. And expecting URLs >>> to stay halfway stable isn't a novel or absurd thing in any sort of way. >>> >>> I think the whole project of pruning the release notes was done hastily >>> and carelessly. At a much larger scope than necessarily apparent from >>> the mailing list discussions. >> >> What would you suggest we do? > > I think the ship has largely sailed. Not do things like this again, I > guess. I was looking for what you provided below in terms of what you would like the ongoing behavior to be. > isn't all that's needed to rename is_released to exists_as_branch, and > remove the testing=0 condition? I forget what the original "hairiness" could have been, and it may have been getting all the logic correct originally on pgweb was a beast. However, yes, it is that simple, patch attached. I tested it with a current devel branch, a "beta" branch, and a released branch, and everything worked as expected. If no objections, I can apply soon. Thanks, Jonathan
Attachment
Hi, On 2019-10-30 19:06:49 -0400, Jonathan S. Katz wrote: > If no objections, I can apply soon. Cool. > diff --git a/pgweb/docs/views.py b/pgweb/docs/views.py > index 1480903c..daea801e 100644 > --- a/pgweb/docs/views.py > +++ b/pgweb/docs/views.py > @@ -80,7 +80,7 @@ def docpage(request, version, filename): > # a) viewing the docs for a version that does not exist yet (e.g. active > # development before an initial beta) OR > # b) viewing the docs for a beta version > - is_released = Version.objects.filter(tree=release_version, testing=0).exists() if version == "devel" else True > + is_released = Version.objects.filter(tree=release_version).exists() if version == "devel" else True > # If we are viewing a released version of the release notesand the > # release versions do not match, then we redirect > if is_released and release_version != ver: I'd probably still rename is_released, given that it's only released at a beta at that point :) Greetings, Andres Freund
On 10/30/19 7:37 PM, Andres Freund wrote: > Hi, > > On 2019-10-30 19:06:49 -0400, Jonathan S. Katz wrote: >> If no objections, I can apply soon. > > Cool. > > >> diff --git a/pgweb/docs/views.py b/pgweb/docs/views.py >> index 1480903c..daea801e 100644 >> --- a/pgweb/docs/views.py >> +++ b/pgweb/docs/views.py >> @@ -80,7 +80,7 @@ def docpage(request, version, filename): >> # a) viewing the docs for a version that does not exist yet (e.g. active >> # development before an initial beta) OR >> # b) viewing the docs for a beta version >> - is_released = Version.objects.filter(tree=release_version, testing=0).exists() if version == "devel" else True >> + is_released = Version.objects.filter(tree=release_version).exists() if version == "devel" else True >> # If we are viewing a released version of the release notesand the >> # release versions do not match, then we redirect >> if is_released and release_version != ver: > > I'd probably still rename is_released, given that it's only released at > a beta at that point :) I prefer green paint on my walls ;) Looking over the code, I need to update the comment around it anyway, so I'll call it "is_branched", tidy up the comments, and push. Links should be live again ~10 mins from this email. Jonathan