Обсуждение: Documentation: 21.5. Default Roles

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/12/default-roles.html
Description:

The title is wrong.   The roles are not defaults; they are predefined and
privileged.  The title suggests that a user should expect  to be assigned
these roles.   "21.5 Sub-Administrator Roles"  would be accurate--improving
clarity over all  and removing any need to explain why postgres is not in
this list of roles.


THE EXISTING 1st Paragraph:

PostgreSQL provides a set of default roles which provide access to certain,
commonly needed, privileged capabilities and information. Administrators can
GRANT these roles to users and/or other roles in their environment,
providing those users with access to the specified capabilities and
information.

A possible replacement:

PostgreSQL provides predefined roles which allow access to various actions
and information  otherwise reserved to superusers.
 Administrators can GRANT these roles like any other role,  but these roles
are also special for allowing abilities not  defined by any standard. 

Additionally:  "commonly"  above is confusing because the "administrative"
context has not been introduced.

In the paragraph  following the table, the 2nd sentence starts:

They grant a set of common privileges allowing the role to read various
useful configuration settings,

is better:

They grant a set of privileges allowing the role to read various
configuration settings,

"Common" and "useful"  are just noise at best.

 Everywhere in the section "default roles"  should be "predefined roles".
Though  a note of the old title could  be helpful to some searchers.

Thank you.

On Fri, Dec 27, 2019 at 05:44:10AM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/12/default-roles.html
> Description:
> 
> The title is wrong.   The roles are not defaults; they are predefined and
> privileged.  The title suggests that a user should expect  to be assigned
> these roles.   "21.5 Sub-Administrator Roles"  would be accurate--improving
> clarity over all  and removing any need to explain why postgres is not in
> this list of roles.
> 

Good points.  I have developed the attached documentation patch which
includes your ideas.

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

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

Greetings,

* PG Doc comments form (noreply@postgresql.org) wrote:
> The title is wrong.   The roles are not defaults; they are predefined and
> privileged.  The title suggests that a user should expect  to be assigned
> these roles.   "21.5 Sub-Administrator Roles"  would be accurate--improving
> clarity over all  and removing any need to explain why postgres is not in
> this list of roles.

"postgres" isn't in the list because there is no default "postgres"
role.  There is a role created that's a superuser role that's given the
same name as the user who is running 'initdb', but you can change that
if you want.  The roles that are listed are, indeed, the default roles
that the PG system comes with- and no others.

> PostgreSQL provides predefined roles which allow access to various actions
> and information  otherwise reserved to superusers.

Oracle uses 'predefined' as the term, while SQL server talks about
"Server-Level" and "Database-Level" roles.  We don't have database-level
roles yet but it seems entirely reasonable to me that we'd want
something like that in the future (eg: a role that's able to read all of
the data from a given database), so I'd be more inclined to go with the
SQL server terminology here, if we're going to make any change.

> Though  a note of the old title could  be helpful to some searchers.

And that we've had them around for a number of years now is what makes
me hesistate to make a change unless it's very clearly a good
improvement and I'm not entirely sure that this is one.

If you'd really like to have fun though, you might check out
https://www.postgresql.org/docs/current/user-manag.html which talks
about "Database Roles" even though what we have are actually Cluster
roles.  Maybe we should just remove "Database" from that whole section
and just talk about "Roles"...  (happened on this while reviewing what
google returned for various searches while thinking about this change).

Thanks,

Stephen

On Fri, 2019-12-27 at 12:16 -0500, Bruce Momjian wrote:
> On Fri, Dec 27, 2019 at 05:44:10AM +0000, PG Doc comments form wrote:
> > The following documentation comment has been logged on the website:
> > 
> > Page: https://www.postgresql.org/docs/12/default-roles.html
> > Description:
> > 
> > The title is wrong.   The roles are not defaults; they are predefined and
> > privileged.  The title suggests that a user should expect  to be assigned
> > these roles.   "21.5 Sub-Administrator Roles"  would be accurate--improving
> > clarity over all  and removing any need to explain why postgres is not in
> > this list of roles.
> > 
> 
> Good points.  I have developed the attached documentation patch which
> includes your ideas.

+1

I think that "predefined role" is better than "default role".

Yours,
Laurenz Albe
-- 
Cybertec | https://www.cybertec-postgresql.com

On Tue, Jan  7, 2020 at 11:46:31AM +0100, Laurenz Albe wrote:
> On Fri, 2019-12-27 at 12:16 -0500, Bruce Momjian wrote:
> > On Fri, Dec 27, 2019 at 05:44:10AM +0000, PG Doc comments form wrote:
> > > The following documentation comment has been logged on the website:
> > > 
> > > Page: https://www.postgresql.org/docs/12/default-roles.html
> > > Description:
> > > 
> > > The title is wrong.   The roles are not defaults; they are predefined and
> > > privileged.  The title suggests that a user should expect  to be assigned
> > > these roles.   "21.5 Sub-Administrator Roles"  would be accurate--improving
> > > clarity over all  and removing any need to explain why postgres is not in
> > > this list of roles.
> > > 
> > 
> > Good points.  I have developed the attached documentation patch which
> > includes your ideas.
> 
> +1
> 
> I think that "predefined role" is better than "default role".

Thanks, patch applied through 9.6.

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

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

Greetings,

* Bruce Momjian (bruce@momjian.us) wrote:
> On Tue, Jan  7, 2020 at 11:46:31AM +0100, Laurenz Albe wrote:
> > On Fri, 2019-12-27 at 12:16 -0500, Bruce Momjian wrote:
> > > On Fri, Dec 27, 2019 at 05:44:10AM +0000, PG Doc comments form wrote:
> > > > The following documentation comment has been logged on the website:
> > > >
> > > > Page: https://www.postgresql.org/docs/12/default-roles.html
> > > > Description:
> > > >
> > > > The title is wrong.   The roles are not defaults; they are predefined and
> > > > privileged.  The title suggests that a user should expect  to be assigned
> > > > these roles.   "21.5 Sub-Administrator Roles"  would be accurate--improving
> > > > clarity over all  and removing any need to explain why postgres is not in
> > > > this list of roles.
> > > >
> > >
> > > Good points.  I have developed the attached documentation patch which
> > > includes your ideas.
> >
> > +1
> >
> > I think that "predefined role" is better than "default role".
>
> Thanks, patch applied through 9.6.

Erm, I didn't agree with this and pointed to reasons why it was based,
for starters, on a misunderstanding and further wasn't a particularly
good idea anyway.  I'm not happy that it was committed, and to have been
back-patched strikes me as even worse.  What about existing links to
things like: https://www.postgresql.org/docs/9.6/default-roles.html
which will now be broken, like from here?:

https://paquier.xyz/postgresql-2/postgres-11-new-system-roles/

Or that the documentation wasn't properly updated to reflect this change
as a simple "git grep 'default role'" would have shown?  There's at
least 5 references still to 'default role' in the documentation after
this commit.

Not to mention that, with this patch, we now have confusion between
things like 'DEFAULT_ROLE_WRITE_SERVER_FILES' in the code vs. the
documentation.

In short, I don't agree with this change, which strikes me as looking
largely like it's trying to make PG look more like Oracle than anything
else, but if we're going to move in this direction we should only be
doing so in master and we should be much more careful making sure that
the documentation, at least, is updated and consistent and that
appropriate comments are made to the code to explain that DEFAULT_ROLE
in the code is referring to "predefined roles" (or we should change the
code, though I can understand if there's argument that doing so would
create unnecessary back-patching hazards..  though there isn't all
*that* much code, so I could go either way on that myself).

Thanks,

Stephen

On Tue, Jan 14, 2020 at 02:45:02PM -0500, Stephen Frost wrote:
> > > I think that "predefined role" is better than "default role".
> > 
> > Thanks, patch applied through 9.6.
> 
> Erm, I didn't agree with this and pointed to reasons why it was based,
> for starters, on a misunderstanding and further wasn't a particularly
> good idea anyway.  I'm not happy that it was committed, and to have been
> back-patched strikes me as even worse.  What about existing links to
> things like: https://www.postgresql.org/docs/9.6/default-roles.html
> which will now be broken, like from here?:

I talked to Stephen on the phone and he is going to fix the doc areas I
missed, and add some C comments.  :-)  Thanks.

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

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

Hi,

On Tue, Jan 14, 2020 at 02:45:02PM -0500, Stephen Frost wrote:
> * Bruce Momjian (bruce@momjian.us) wrote:
> > On Tue, Jan  7, 2020 at 11:46:31AM +0100, Laurenz Albe wrote:
> > > On Fri, 2019-12-27 at 12:16 -0500, Bruce Momjian wrote:
> > > > On Fri, Dec 27, 2019 at 05:44:10AM +0000, PG Doc comments form wrote:
> > > > > The following documentation comment has been logged on the website:
> > > > > 
> > > > > Page: https://www.postgresql.org/docs/12/default-roles.html
> > > > > Description:
> > > > > 
> > > > > The title is wrong.   The roles are not defaults; they are predefined and
> > > > > privileged.  The title suggests that a user should expect  to be assigned
> > > > > these roles.   "21.5 Sub-Administrator Roles"  would be accurate--improving
> > > > > clarity over all  and removing any need to explain why postgres is not in
> > > > > this list of roles.
> > > > > 
> > > > 
> > > > Good points.  I have developed the attached documentation patch which
> > > > includes your ideas.
> > > 
> > > I think that "predefined role" is better than "default role".
> > 
> > Thanks, patch applied through 9.6.
> 
> Erm, I didn't agree with this and pointed to reasons why it was based,
> for starters, on a misunderstanding and further wasn't a particularly

I went to the documentation for clarity.  I read a section that was not
pertinent to my issue because it is poorly titled.  These roles
are not defaults in any sense.

> good idea anyway.  I'm not happy that it was committed, and to have been
> back-patched strikes me as even worse.  What about existing links to
> things like: https://www.postgresql.org/docs/9.6/default-roles.html
> which will now be broken, like from here?:
> 
> https://paquier.xyz/postgresql-2/postgres-11-new-system-roles/

I would hope to find correct documentation somewhere--that somewhere
should be Postgresql's own documentation.

> least 5 references still to 'default role' in the documentation after

> things like 'DEFAULT_ROLE_WRITE_SERVER_FILES' in the code vs. the

No doubt, there is more documentation needing fixing.  I am impressed
by the quality of Pg's documentation overall.

> In short, I don't agree with this change, which strikes me as looking
> largely like it's trying to make PG look more like Oracle than anything
> else, but if we're going to move in this direction we should only be
> doing so in master and

It is incorrect to suppose that I am trying to "make PG look ... like
Oracle".  I don't know what Oracle looks like; I've only used msql (not
mysql) and Pg.

"Only .. in master" is a future far away.  Less so for you.


Stephen, thank you.
Rob

On 2020/01/19 12:56, R Ransbottom wrote:
> Hi,
> 
> On Tue, Jan 14, 2020 at 02:45:02PM -0500, Stephen Frost wrote:
>> * Bruce Momjian (bruce@momjian.us) wrote:
>>> On Tue, Jan  7, 2020 at 11:46:31AM +0100, Laurenz Albe wrote:
>>>> On Fri, 2019-12-27 at 12:16 -0500, Bruce Momjian wrote:
>>>>> On Fri, Dec 27, 2019 at 05:44:10AM +0000, PG Doc comments form wrote:
>>>>>> The following documentation comment has been logged on the website:
>>>>>>
>>>>>> Page: https://www.postgresql.org/docs/12/default-roles.html
>>>>>> Description:
>>>>>>
>>>>>> The title is wrong.   The roles are not defaults; they are predefined and
>>>>>> privileged.  The title suggests that a user should expect  to be assigned
>>>>>> these roles.   "21.5 Sub-Administrator Roles"  would be accurate--improving
>>>>>> clarity over all  and removing any need to explain why postgres is not in
>>>>>> this list of roles.
>>>>>>
>>>>>
>>>>> Good points.  I have developed the attached documentation patch which
>>>>> includes your ideas.
>>>>
>>>> I think that "predefined role" is better than "default role".
>>>
>>> Thanks, patch applied through 9.6.
>>
>> Erm, I didn't agree with this and pointed to reasons why it was based,
>> for starters, on a misunderstanding and further wasn't a particularly
> 
> I went to the documentation for clarity.  I read a section that was not
> pertinent to my issue because it is poorly titled.  These roles
> are not defaults in any sense.
> 
>> good idea anyway.  I'm not happy that it was committed, and to have been
>> back-patched strikes me as even worse.  What about existing links to
>> things like: https://www.postgresql.org/docs/9.6/default-roles.html
>> which will now be broken, like from here?:
>>
>> https://paquier.xyz/postgresql-2/postgres-11-new-system-roles/
> 
> I would hope to find correct documentation somewhere--that somewhere
> should be Postgresql's own documentation.

Indeed, however it's important that the PostgreSQL documentation remains
stable for released versions.

As-is, the current patch set would result in the term "default role(s)"
disappearing from the documentation in the next minor release, which is
bound to cause confusion for anyone searching the documentation for the
term they're familiar with (unless they happen to be reading this thread
or following the git commit log). Cue cries of "OMG Postgres removed a
feature in a minor release!!!?!!".

And as Stephen mentions, it will break a lot of secondary documentation -
not just blogs but things like internal training  materials etc.

If this change is made (which I'm personally not against), then it should be
only from PostgreSQL 13. For 9.6 ~ 12, IMHO it would be better to tweak the
existing documentation to somehow mention that "default roles" should be
thought of as "prefined roles", and note they will be called this from Pg13.


Regards

Ian Barwick

-- 
Ian Barwick                   https://www.2ndQuadrant.com/
  PostgreSQL Development, 24x7 Support, Training & Services

On Mon, Jan 20, 2020 at 12:23:48PM +0900, Ian Barwick wrote:
> > I would hope to find correct documentation somewhere--that somewhere
> > should be Postgresql's own documentation.
> 
> Indeed, however it's important that the PostgreSQL documentation remains
> stable for released versions.
> 
> As-is, the current patch set would result in the term "default role(s)"
> disappearing from the documentation in the next minor release, which is
> bound to cause confusion for anyone searching the documentation for the
> term they're familiar with (unless they happen to be reading this thread
> or following the git commit log). Cue cries of "OMG Postgres removed a
> feature in a minor release!!!?!!".
> 
> And as Stephen mentions, it will break a lot of secondary documentation -
> not just blogs but things like internal training  materials etc.
> 
> If this change is made (which I'm personally not against), then it should be
> only from PostgreSQL 13. For 9.6 ~ 12, IMHO it would be better to tweak the
> existing documentation to somehow mention that "default roles" should be
> thought of as "prefined roles", and note they will be called this from Pg13.

Usually when I apply "wording" doc patches to head only, someone
complains that it should be backpatched, so I did that in this case.  If
we want to change that idea, we need to agree on the criteria.

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

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

On Mon, Jan 20, 2020 at 06:45:16PM +0000, Simon Riggs wrote:
> On Mon, 20 Jan 2020 at 16:03, Bruce Momjian <bruce@momjian.us> wrote:
>     Usually when I apply "wording" doc patches to head only, someone
>     complains that it should be backpatched, so I did that in this case.  If
>     we want to change that idea, we need to agree on the criteria.
> 
> True, but it's not a wording patch, you're entirely renaming a feature.
> 
> I agree with the change of default to predefined, but it shouldn't be
> backpatched.
> 
> There should be a comment in there that it was previously known as "default
> roles", with indexed terms for both.

Well, I am renaming the documentation label for the feature.  Is that
different than wording?  I guess I can see that.  If everyone agrees I
can revert the backpatch, but I don't want to do that if other people
are going to say this should be backpatched.

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

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

On Mon, 2020-01-20 at 17:13 -0500, Bruce Momjian wrote:
> Well, I am renaming the documentation label for the feature.  Is that
> different than wording?  I guess I can see that.  If everyone agrees I
> can revert the backpatch, but I don't want to do that if other people
> are going to say this should be backpatched.

I for one think that it should be backpatched, as long as the
old link keeps working.

Yours,
Laurenz Albe

On Tue, Jan 21, 2020 at 10:06:43AM +0100, Laurenz Albe wrote:
> On Mon, 2020-01-20 at 17:13 -0500, Bruce Momjian wrote:
> > Well, I am renaming the documentation label for the feature.  Is that
> > different than wording?  I guess I can see that.  If everyone agrees I
> > can revert the backpatch, but I don't want to do that if other people
> > are going to say this should be backpatched.
> 
> I for one think that it should be backpatched, as long as the
> old link keeps working.

I looked at that option.  If the section was a hash reference,
"#section_name", we could just add another hash, but in this case the
section name is part of the file name:

    https://www.postgresql.org/docs/12/default-roles.html

We can make that work in a backward-compatible way by changing the
displayed section title, but not the file name.  I am not sure if that
would confuse people though.  We could also add a redirect at the web
server level, but then you have to start to wonder whether the entire
rename clarification is worth it for back branches.

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

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

Bruce Momjian <bruce@momjian.us> writes:
> I looked at that option.  If the section was a hash reference,
> "#section_name", we could just add another hash, but in this case the
> section name is part of the file name:
>     https://www.postgresql.org/docs/12/default-roles.html

Yeah, <sect1> IDs propagate into HTML page names.

> We can make that work in a backward-compatible way by changing the
> displayed section title, but not the file name.  I am not sure if that
> would confuse people though.

I think that's a really bad idea.

> We could also add a redirect at the web
> server level, but then you have to start to wonder whether the entire
> rename clarification is worth it for back branches.

Well, this is a question for the www list not here.  It might be a lot
easier for them to support a redirect that works the same across all
branches ... or then again, maybe not.  But we have to have a redirect,
else external links pointing at this page will be broken.

We have done page renames with redirects in the past, if memory serves,
so it's possible.  But I don't know details.

            regards, tom lane

On Mon, Jan 20, 2020 at 12:23:48PM +0900, Ian Barwick wrote:
> On 2020/01/19 12:56, R Ransbottom wrote:

> > I would hope to find correct documentation somewhere--that somewhere

> Indeed, however it's important that the PostgreSQL documentation remains
> stable for released versions.

> As-is, the current patch set would result in the term "default role(s)"
> disappearing from the documentation in the next minor release, which is
> bound to cause confusion for anyone searching the documentation for the
> term they're familiar with (unless they happen to be reading this thread
> or following the git commit log). Cue cries of "OMG Postgres removed a
> feature in a minor release!!!?!!".

> And as Stephen mentions, it will break a lot of secondary documentation -
> not just blogs but things like internal training  materials etc.

> If this change is made (which I'm personally not against), then it should be
> only from PostgreSQL 13. For 9.6 ~ 12, IMHO it would be better to tweak the
> existing documentation to somehow mention that "default roles" should be
> thought of as "prefined roles", and note they will be called this from Pg13.

Ian, agreed modulo 13.

The current section(s) could forward readers to a revised section.  The
DEFAULT_ROLE_* stuff could carry two names to allow a comprehensive fix
in 12.X.  That could allow the deprecation and misinformation to end one
EoL sooner.

Thanks all.
Rob

On Thu, Jan 23, 2020 at 07:12:08PM -0500, R Ransbottom wrote:
> On Mon, Jan 20, 2020 at 12:23:48PM +0900, Ian Barwick wrote:
> > On 2020/01/19 12:56, R Ransbottom wrote:
> 
> > > I would hope to find correct documentation somewhere--that somewhere
> 
> > Indeed, however it's important that the PostgreSQL documentation remains
> > stable for released versions.
> 
> > As-is, the current patch set would result in the term "default role(s)"
> > disappearing from the documentation in the next minor release, which is
> > bound to cause confusion for anyone searching the documentation for the
> > term they're familiar with (unless they happen to be reading this thread
> > or following the git commit log). Cue cries of "OMG Postgres removed a
> > feature in a minor release!!!?!!".
> 
> > And as Stephen mentions, it will break a lot of secondary documentation -
> > not just blogs but things like internal training  materials etc.
> 
> > If this change is made (which I'm personally not against), then it should be
> > only from PostgreSQL 13. For 9.6 ~ 12, IMHO it would be better to tweak the
> > existing documentation to somehow mention that "default roles" should be
> > thought of as "prefined roles", and note they will be called this from Pg13.
> 
> Ian, agreed modulo 13.
> 
> The current section(s) could forward readers to a revised section.  The
> DEFAULT_ROLE_* stuff could carry two names to allow a comprehensive fix
> in 12.X.  That could allow the deprecation and misinformation to end one
> EoL sooner.

With minor releases coming next week, and no movement on doing web
redirects, and no clarity on what this is missing even in master, I will
revert this patch in all branches soon.  I think everyone agrees the new
documentation title is better, but we don't want to break things or add
inconsistency to do it.

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

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

On 2/3/20 3:42 PM, Bruce Momjian wrote:
> On Thu, Jan 23, 2020 at 07:12:08PM -0500, R Ransbottom wrote:
>> On Mon, Jan 20, 2020 at 12:23:48PM +0900, Ian Barwick wrote:
>>> On 2020/01/19 12:56, R Ransbottom wrote:
>>
>>>> I would hope to find correct documentation somewhere--that somewhere
>>
>>> Indeed, however it's important that the PostgreSQL documentation remains
>>> stable for released versions.
>>
>>> As-is, the current patch set would result in the term "default role(s)"
>>> disappearing from the documentation in the next minor release, which is
>>> bound to cause confusion for anyone searching the documentation for the
>>> term they're familiar with (unless they happen to be reading this thread
>>> or following the git commit log). Cue cries of "OMG Postgres removed a
>>> feature in a minor release!!!?!!".
>>
>>> And as Stephen mentions, it will break a lot of secondary documentation -
>>> not just blogs but things like internal training  materials etc.
>>
>>> If this change is made (which I'm personally not against), then it should be
>>> only from PostgreSQL 13. For 9.6 ~ 12, IMHO it would be better to tweak the
>>> existing documentation to somehow mention that "default roles" should be
>>> thought of as "prefined roles", and note they will be called this from Pg13.
>>
>> Ian, agreed modulo 13.
>>
>> The current section(s) could forward readers to a revised section.  The
>> DEFAULT_ROLE_* stuff could carry two names to allow a comprehensive fix
>> in 12.X.  That could allow the deprecation and misinformation to end one
>> EoL sooner.
>
> With minor releases coming next week, and no movement on doing web
> redirects, and no clarity on what this is missing even in master, I will
> revert this patch in all branches soon.  I think everyone agrees the new
> documentation title is better, but we don't want to break things or add
> inconsistency to do it.

Sorry, I missed the original comment on the "web redirects"

So, if there was something done to redirect people from specific
deprecated documentation pages historically, it was before my time. Most
of the redirects have been as general purposes ones (e.g. /docs/12), the
rules we put in for getting rid of "static", and the release notes,
which still receives some negative feedback towards it for different
reasons (though I think overall the effort was well-received). Anyway,
if we had a redirect in place, I'd want us to do it well.


I don't know if it's possible...but if we were able to make a change in
the doc source to say "this page is now this page" either as a
standalone page, or generated a HTML page that automatically redirects,
that may solve the issue. Or if we can have a "ghost page" available
with the old link, perhaps we can put something into pgweb to
automatically redirect to the new page. Other than that, the only quick
solution I see is to hardcode it, which I'm not a fan of.

So from a pgweb standpoint, the safe thing would be to do nothing with
the URL. If you could keep the URL but change the page title, perhaps
that would suffice?

Jonathan

On 2020-Feb-03, Jonathan S. Katz wrote:

> So, if there was something done to redirect people from specific
> deprecated documentation pages historically, it was before my time. Most
> of the redirects have been as general purposes ones (e.g. /docs/12), the
> rules we put in for getting rid of "static", and the release notes,
> which still receives some negative feedback towards it for different
> reasons (though I think overall the effort was well-received). Anyway,
> if we had a redirect in place, I'd want us to do it well.

I +1 changing the title and +1 having the redirect.  That said, I think
people landing in a page titled "predefined roles" when they're looking
for a page titled "default roles" would be quite confused for a while
and perhaps continue to search for the page they think they're looking
for.  (I know, it has happened to me.)  I suggest we add a very short
paragraph --maybe a <note>-- to the effect that feature-X used to be
called feature-Y, immediately following the section title.

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

On Mon, Feb 3, 2020 at 9:59 PM Jonathan S. Katz <jkatz@postgresql.org> wrote:
>
> On 2/3/20 3:42 PM, Bruce Momjian wrote:
> > On Thu, Jan 23, 2020 at 07:12:08PM -0500, R Ransbottom wrote:
> >> On Mon, Jan 20, 2020 at 12:23:48PM +0900, Ian Barwick wrote:
> >>> On 2020/01/19 12:56, R Ransbottom wrote:
> >>
> >>>> I would hope to find correct documentation somewhere--that somewhere
> >>
> >>> Indeed, however it's important that the PostgreSQL documentation remains
> >>> stable for released versions.
> >>
> >>> As-is, the current patch set would result in the term "default role(s)"
> >>> disappearing from the documentation in the next minor release, which is
> >>> bound to cause confusion for anyone searching the documentation for the
> >>> term they're familiar with (unless they happen to be reading this thread
> >>> or following the git commit log). Cue cries of "OMG Postgres removed a
> >>> feature in a minor release!!!?!!".
> >>
> >>> And as Stephen mentions, it will break a lot of secondary documentation -
> >>> not just blogs but things like internal training  materials etc.
> >>
> >>> If this change is made (which I'm personally not against), then it should be
> >>> only from PostgreSQL 13. For 9.6 ~ 12, IMHO it would be better to tweak the
> >>> existing documentation to somehow mention that "default roles" should be
> >>> thought of as "prefined roles", and note they will be called this from Pg13.
> >>
> >> Ian, agreed modulo 13.
> >>
> >> The current section(s) could forward readers to a revised section.  The
> >> DEFAULT_ROLE_* stuff could carry two names to allow a comprehensive fix
> >> in 12.X.  That could allow the deprecation and misinformation to end one
> >> EoL sooner.
> >
> > With minor releases coming next week, and no movement on doing web
> > redirects, and no clarity on what this is missing even in master, I will
> > revert this patch in all branches soon.  I think everyone agrees the new
> > documentation title is better, but we don't want to break things or add
> > inconsistency to do it.
>
> Sorry, I missed the original comment on the "web redirects"

Same here. It was buried a little too deep in an existing therad.

>
> So, if there was something done to redirect people from specific
> deprecated documentation pages historically, it was before my time. Most
> of the redirects have been as general purposes ones (e.g. /docs/12), the
> rules we put in for getting rid of "static", and the release notes,
> which still receives some negative feedback towards it for different
> reasons (though I think overall the effort was well-received). Anyway,
> if we had a redirect in place, I'd want us to do it well.

We have something close to it in commit
496416ceda9c1015d9e7a6ef4b4fb18dae8a8d4e. But that doesn't actually
generate redirects when requests are coming in from the outside -- it
just makes sure our *internal* links can survive the rename of a file
between branches.

So it may not be exactly what's being looked for here, but it might be
a starting point. Probably the same underlying mapping table could be
used, but I haven't investigated that closely enough to say if it's
doable at this point, just that it's a starting point.

Using this feature to handle the rename of a file *between* major
versions, thus leaving the changes in master, should be safe (as long
as we add an entry to that table in pgweb).

As for back branches, I think we have to say that it's too close to
the minor release to safely have something done in pgweb before then.

-- 
 Magnus Hagander
 Me: https://www.hagander.net/
 Work: https://www.redpill-linpro.com/

Greetings,

* Alvaro Herrera (alvherre@2ndquadrant.com) wrote:
> On 2020-Feb-03, Jonathan S. Katz wrote:
>
> > So, if there was something done to redirect people from specific
> > deprecated documentation pages historically, it was before my time. Most
> > of the redirects have been as general purposes ones (e.g. /docs/12), the
> > rules we put in for getting rid of "static", and the release notes,
> > which still receives some negative feedback towards it for different
> > reasons (though I think overall the effort was well-received). Anyway,
> > if we had a redirect in place, I'd want us to do it well.
>
> I +1 changing the title and +1 having the redirect.  That said, I think
> people landing in a page titled "predefined roles" when they're looking
> for a page titled "default roles" would be quite confused for a while
> and perhaps continue to search for the page they think they're looking
> for.  (I know, it has happened to me.)  I suggest we add a very short
> paragraph --maybe a <note>-- to the effect that feature-X used to be
> called feature-Y, immediately following the section title.

I'm a bit confused as it sounded like having the redirect wouldn't be
easy to do..  I also agree that keeping the URL the same as today but
changing that URL to be talking about 'predefined roles' would be quite
confusing.

Having some kind of landing page with the existing URL that had a link
for people to click on to get to the new URL seems like it would
possibly work.  I'd be happier with having that done in master and
keeping the back-branches as-is, since I don't really like the idea that
we're retroactively renaming a feature in our existing releases.

That said, if we at least have the landing page then at least people
will be less likely to be confused.

Thanks,

Stephen

On 2/4/20 3:34 AM, Magnus Hagander wrote:
> On Mon, Feb 3, 2020 at 9:59 PM Jonathan S. Katz <jkatz@postgresql.org> wrote:

>> So, if there was something done to redirect people from specific
>> deprecated documentation pages historically, it was before my time. Most
>> of the redirects have been as general purposes ones (e.g. /docs/12), the
>> rules we put in for getting rid of "static", and the release notes,
>> which still receives some negative feedback towards it for different
>> reasons (though I think overall the effort was well-received). Anyway,
>> if we had a redirect in place, I'd want us to do it well.
>
> We have something close to it in commit
> 496416ceda9c1015d9e7a6ef4b4fb18dae8a8d4e. But that doesn't actually
> generate redirects when requests are coming in from the outside -- it
> just makes sure our *internal* links can survive the rename of a file
> between branches.

Ah cool, didn't realize we had this feature :)

> So it may not be exactly what's being looked for here, but it might be
> a starting point. Probably the same underlying mapping table could be
> used, but I haven't investigated that closely enough to say if it's
> doable at this point, just that it's a starting point.

Yeah. It could be as simple as having a flag on it to say it should
redirect if the old file (presumably "file2" in the model) is hit. I'm
saying this without diving into the mechanics of the code.

> Using this feature to handle the rename of a file *between* major
> versions, thus leaving the changes in master, should be safe (as long
> as we add an entry to that table in pgweb).
>
> As for back branches, I think we have to say that it's too close to
> the minor release to safely have something done in pgweb before then.

This part I agree on, but let's sync offline to see if there is
something within reason, with a preference to *not* rush if we're
worried about breaking something right before release.

Jonathan

On Tue, Feb  4, 2020 at 11:31:19AM -0500, Jonathan Katz wrote:
> > Using this feature to handle the rename of a file *between* major
> > versions, thus leaving the changes in master, should be safe (as long
> > as we add an entry to that table in pgweb).
> > 
> > As for back branches, I think we have to say that it's too close to
> > the minor release to safely have something done in pgweb before then.
> 
> This part I agree on, but let's sync offline to see if there is
> something within reason, with a preference to *not* rush if we're
> worried about breaking something right before release.

Folks, is it Thursday.  Can we revert this and return to it when we are
not rushed?  Alternatively, can someone who controls all the moving
parts, like  redirects and Stephen's patch additions take ownership of
this issue, with authority to revert the patch if things are too close?

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

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

On 2/6/20 12:11 AM, Bruce Momjian wrote:
> On Tue, Feb  4, 2020 at 11:31:19AM -0500, Jonathan Katz wrote:
>>> Using this feature to handle the rename of a file *between* major
>>> versions, thus leaving the changes in master, should be safe (as long
>>> as we add an entry to that table in pgweb).
>>>
>>> As for back branches, I think we have to say that it's too close to
>>> the minor release to safely have something done in pgweb before then.
>>
>> This part I agree on, but let's sync offline to see if there is
>> something within reason, with a preference to *not* rush if we're
>> worried about breaking something right before release.
>
> Folks, is it Thursday.  Can we revert this and return to it when we are
> not rushed?  Alternatively, can someone who controls all the moving
> parts, like  redirects and Stephen's patch additions take ownership of
> this issue, with authority to revert the patch if things are too close?

Magnus and I briefly discussed what it would take, but the probability
of having the redirects ready on pgweb before the release is
slim-to-none, as we'd like to thoroughly test.

We can start experimenting with it now, and commit a fix after the release.

I don't have the power to revert changes directly to the documentation
in core, so I cannot take ownership of that part. However, I am happy to
own the completion of the redirect feature.

Thanks,

Jonathan

Greetings,

* Jonathan S. Katz (jkatz@postgresql.org) wrote:
> On 2/6/20 12:11 AM, Bruce Momjian wrote:
> > On Tue, Feb  4, 2020 at 11:31:19AM -0500, Jonathan Katz wrote:
> >>> Using this feature to handle the rename of a file *between* major
> >>> versions, thus leaving the changes in master, should be safe (as long
> >>> as we add an entry to that table in pgweb).
> >>>
> >>> As for back branches, I think we have to say that it's too close to
> >>> the minor release to safely have something done in pgweb before then.
> >>
> >> This part I agree on, but let's sync offline to see if there is
> >> something within reason, with a preference to *not* rush if we're
> >> worried about breaking something right before release.
> >
> > Folks, is it Thursday.  Can we revert this and return to it when we are
> > not rushed?  Alternatively, can someone who controls all the moving
> > parts, like  redirects and Stephen's patch additions take ownership of
> > this issue, with authority to revert the patch if things are too close?
>
> Magnus and I briefly discussed what it would take, but the probability
> of having the redirects ready on pgweb before the release is
> slim-to-none, as we'd like to thoroughly test.
>
> We can start experimenting with it now, and commit a fix after the release.
>
> I don't have the power to revert changes directly to the documentation
> in core, so I cannot take ownership of that part. However, I am happy to
> own the completion of the redirect feature.

I can own the core bits, since you've offered to take on the web pieces.
:)

Given the discussion, barring objections, I'll revert the changes
tomorrow and then work with Jonathan and Magnus to try and get the
website redirect stuff working so that we can make this change in a
future release.

Thanks,

Stephen

On Thu, Feb  6, 2020 at 11:05:04AM -0500, Stephen Frost wrote:
> * Jonathan S. Katz (jkatz@postgresql.org) wrote:
> > I don't have the power to revert changes directly to the documentation
> > in core, so I cannot take ownership of that part. However, I am happy to
> > own the completion of the redirect feature.
> 
> I can own the core bits, since you've offered to take on the web pieces.
> :)
> 
> Given the discussion, barring objections, I'll revert the changes
> tomorrow and then work with Jonathan and Magnus to try and get the
> website redirect stuff working so that we can make this change in a
> future release.

OK, thanks everyone.

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

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

Stephen Frost <sfrost@snowman.net> writes:
> * Jonathan S. Katz (jkatz@postgresql.org) wrote:
>> On 2/6/20 12:11 AM, Bruce Momjian wrote:
>>> Folks, is it Thursday.  Can we revert this and return to it when we are
>>> not rushed?  Alternatively, can someone who controls all the moving
>>> parts, like  redirects and Stephen's patch additions take ownership of
>>> this issue, with authority to revert the patch if things are too close?

>> Magnus and I briefly discussed what it would take, but the probability
>> of having the redirects ready on pgweb before the release is
>> slim-to-none, as we'd like to thoroughly test.

> Given the discussion, barring objections, I'll revert the changes
> tomorrow and then work with Jonathan and Magnus to try and get the
> website redirect stuff working so that we can make this change in a
> future release.

It's Sunday afternoon, and nothing has happened, so I took it on
myself to revert this.

            regards, tom lane

On Thu, Feb  6, 2020 at 10:59:09AM -0500, Jonathan Katz wrote:
> On 2/6/20 12:11 AM, Bruce Momjian wrote:
> > On Tue, Feb  4, 2020 at 11:31:19AM -0500, Jonathan Katz wrote:
> >>> Using this feature to handle the rename of a file *between* major
> >>> versions, thus leaving the changes in master, should be safe (as long
> >>> as we add an entry to that table in pgweb).
> >>>
> >>> As for back branches, I think we have to say that it's too close to
> >>> the minor release to safely have something done in pgweb before then.
> >>
> >> This part I agree on, but let's sync offline to see if there is
> >> something within reason, with a preference to *not* rush if we're
> >> worried about breaking something right before release.
> > 
> > Folks, is it Thursday.  Can we revert this and return to it when we are
> > not rushed?  Alternatively, can someone who controls all the moving
> > parts, like  redirects and Stephen's patch additions take ownership of
> > this issue, with authority to revert the patch if things are too close?
> 
> Magnus and I briefly discussed what it would take, but the probability
> of having the redirects ready on pgweb before the release is
> slim-to-none, as we'd like to thoroughly test.
> 
> We can start experimenting with it now, and commit a fix after the release.
> 
> I don't have the power to revert changes directly to the documentation
> in core, so I cannot take ownership of that part. However, I am happy to
> own the completion of the redirect feature.

Jonathan, Stephen, with the minor release done, can we focus on adding
the URL redirect and completing the patch to rename this feature in the
docs?  Thanks.

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

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

On 4/9/20 4:57 PM, Bruce Momjian wrote:
> On Thu, Feb  6, 2020 at 10:59:09AM -0500, Jonathan Katz wrote:
>> On 2/6/20 12:11 AM, Bruce Momjian wrote:
>>> On Tue, Feb  4, 2020 at 11:31:19AM -0500, Jonathan Katz wrote:
>>>>> Using this feature to handle the rename of a file *between* major
>>>>> versions, thus leaving the changes in master, should be safe (as long
>>>>> as we add an entry to that table in pgweb).
>>>>>
>>>>> As for back branches, I think we have to say that it's too close to
>>>>> the minor release to safely have something done in pgweb before then.
>>>>
>>>> This part I agree on, but let's sync offline to see if there is
>>>> something within reason, with a preference to *not* rush if we're
>>>> worried about breaking something right before release.
>>>
>>> Folks, is it Thursday.  Can we revert this and return to it when we are
>>> not rushed?  Alternatively, can someone who controls all the moving
>>> parts, like  redirects and Stephen's patch additions take ownership of
>>> this issue, with authority to revert the patch if things are too close?
>>
>> Magnus and I briefly discussed what it would take, but the probability
>> of having the redirects ready on pgweb before the release is
>> slim-to-none, as we'd like to thoroughly test.
>>
>> We can start experimenting with it now, and commit a fix after the release.
>>
>> I don't have the power to revert changes directly to the documentation
>> in core, so I cannot take ownership of that part. However, I am happy to
>> own the completion of the redirect feature.
>
> Jonathan, Stephen, with the minor release done, can we focus on adding
> the URL redirect and completing the patch to rename this feature in the
> docs?  Thanks.

Yes, I have a prototype for this ready, which I had scrambled together
before the release. I am happy to make it committable in the coming days.

Jonathan

On Thu, Apr  9, 2020 at 08:47:56PM -0400, Jonathan Katz wrote:
> On 4/9/20 4:57 PM, Bruce Momjian wrote:
> > Jonathan, Stephen, with the minor release done, can we focus on adding
> > the URL redirect and completing the patch to rename this feature in the
> > docs?  Thanks.
> 
> Yes, I have a prototype for this ready, which I had scrambled together
> before the release. I am happy to make it committable in the coming days.

Thanks.  Once that is done Stephen can apply my patch with his
additions.

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

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +

On 4/9/20 11:45 PM, Bruce Momjian wrote:
> On Thu, Apr  9, 2020 at 08:47:56PM -0400, Jonathan Katz wrote:
>> On 4/9/20 4:57 PM, Bruce Momjian wrote:
>>> Jonathan, Stephen, with the minor release done, can we focus on adding
>>> the URL redirect and completing the patch to rename this feature in the
>>> docs?  Thanks.
>>
>> Yes, I have a prototype for this ready, which I had scrambled together
>> before the release. I am happy to make it committable in the coming days.
>
> Thanks.  Once that is done Stephen can apply my patch with his
> additions.

Please see attached patch for pgweb that allows for the documentation to
be redirected from a page that is removed to a newer page. The way it works:

- Checks to see if a page is found. If it is, great!
- Now if a page 404s, we first check to see if there is a forwarding
address, i.e. the new page. If it is, we issue a 301 (permanent redirecTt).
- If it's still not found, we abort.

I believe this gives us the desired behavior.

Thoughts on the patch?

Thanks,

Jonathan

Greetings,

* Magnus Hagander (magnus@hagander.net) wrote:
> On Sat, Apr 25, 2020 at 1:38 AM Jonathan S. Katz <jkatz@postgresql.org>
> wrote:
>
> > On 4/9/20 11:45 PM, Bruce Momjian wrote:
> > > On Thu, Apr  9, 2020 at 08:47:56PM -0400, Jonathan Katz wrote:
> > >> On 4/9/20 4:57 PM, Bruce Momjian wrote:
> > >>> Jonathan, Stephen, with the minor release done, can we focus on adding
> > >>> the URL redirect and completing the patch to rename this feature in the
> > >>> docs?  Thanks.
> > >>
> > >> Yes, I have a prototype for this ready, which I had scrambled together
> > >> before the release. I am happy to make it committable in the coming
> > days.
> > >
> > > Thanks.  Once that is done Stephen can apply my patch with his
> > > additions.
> >
> > Please see attached patch for pgweb that allows for the documentation to
> > be redirected from a page that is removed to a newer page. The way it
> > works:
> >
> > - Checks to see if a page is found. If it is, great!
> > - Now if a page 404s, we first check to see if there is a forwarding
> > address, i.e. the new page. If it is, we issue a 301 (permanent redirecTt).
> > - If it's still not found, we abort.
> >
> > I believe this gives us the desired behavior.
> >
> > Thoughts on the patch?
>
>  Looks good to me. Go for it.

What's the plan for how to maintain it going forward?  Just email -docs
and ask someone to perform the update whenever a release is going out..?
Or do we have some kind of better process in mind?

Thanks!

Stephen

On 4/28/20 2:19 PM, Magnus Hagander wrote:
> On Sat, Apr 25, 2020 at 1:38 AM Jonathan S. Katz <jkatz@postgresql.org
> <mailto:jkatz@postgresql.org>> wrote:
>
>     On 4/9/20 11:45 PM, Bruce Momjian wrote:
>     > On Thu, Apr  9, 2020 at 08:47:56PM -0400, Jonathan Katz wrote:
>     >> On 4/9/20 4:57 PM, Bruce Momjian wrote:
>     >>> Jonathan, Stephen, with the minor release done, can we focus on
>     adding
>     >>> the URL redirect and completing the patch to rename this feature
>     in the
>     >>> docs?  Thanks.
>     >>
>     >> Yes, I have a prototype for this ready, which I had scrambled
>     together
>     >> before the release. I am happy to make it committable in the
>     coming days.
>     >
>     > Thanks.  Once that is done Stephen can apply my patch with his
>     > additions.
>
>     Please see attached patch for pgweb that allows for the documentation to
>     be redirected from a page that is removed to a newer page. The way
>     it works:
>
>     - Checks to see if a page is found. If it is, great!
>     - Now if a page 404s, we first check to see if there is a forwarding
>     address, i.e. the new page. If it is, we issue a 301 (permanent
>     redirecTt).
>     - If it's still not found, we abort.
>
>     I believe this gives us the desired behavior.
>
>     Thoughts on the patch?
>
>
>  Looks good to me. Go for it.

This is deployed. Ready for the patch in core.

Thanks!

Jonathan

On 2020-04-10 05:45, Bruce Momjian wrote:
> On Thu, Apr  9, 2020 at 08:47:56PM -0400, Jonathan Katz wrote:
>> On 4/9/20 4:57 PM, Bruce Momjian wrote:
>>> Jonathan, Stephen, with the minor release done, can we focus on adding
>>> the URL redirect and completing the patch to rename this feature in the
>>> docs?  Thanks.
>>
>> Yes, I have a prototype for this ready, which I had scrambled together
>> before the release. I am happy to make it committable in the coming days.
> 
> Thanks.  Once that is done Stephen can apply my patch with his
> additions.

I think we should leave the backbranches alone.  The feature shipped 
with the name as it did, and users know it as such.  If we start 
retroactively renaming all functionality when we change our mind, it 
will create complete madness.  New ideas belong into the master branch.

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

On Tue, Apr 28, 2020 at 04:02:25PM -0400, Jonathan Katz wrote:
> On 4/28/20 2:19 PM, Magnus Hagander wrote:
> > On Sat, Apr 25, 2020 at 1:38 AM Jonathan S. Katz <jkatz@postgresql.org
> > <mailto:jkatz@postgresql.org>> wrote:
> > 
> >     On 4/9/20 11:45 PM, Bruce Momjian wrote:
> >     > On Thu, Apr  9, 2020 at 08:47:56PM -0400, Jonathan Katz wrote:
> >     >> On 4/9/20 4:57 PM, Bruce Momjian wrote:
> >     >>> Jonathan, Stephen, with the minor release done, can we focus on
> >     adding
> >     >>> the URL redirect and completing the patch to rename this feature
> >     in the
> >     >>> docs?  Thanks.
> >     >>
> >     >> Yes, I have a prototype for this ready, which I had scrambled
> >     together
> >     >> before the release. I am happy to make it committable in the
> >     coming days.
> >     >
> >     > Thanks.  Once that is done Stephen can apply my patch with his
> >     > additions.
> > 
> >     Please see attached patch for pgweb that allows for the documentation to
> >     be redirected from a page that is removed to a newer page. The way
> >     it works:
> > 
> >     - Checks to see if a page is found. If it is, great!
> >     - Now if a page 404s, we first check to see if there is a forwarding
> >     address, i.e. the new page. If it is, we issue a 301 (permanent
> >     redirecTt).
> >     - If it's still not found, we abort.
> > 
> >     I believe this gives us the desired behavior.
> > 
> >     Thoughts on the patch?
> > 
> > 
> >  Looks good to me. Go for it.
> 
> This is deployed. Ready for the patch in core.

OK, Stephen, I believe you have a more comprehensive patch to make this
change.  When can you complete it?  The above email is from April.

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

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

Greetings,

* Bruce Momjian (bruce@momjian.us) wrote:
> OK, Stephen, I believe you have a more comprehensive patch to make this
> change.  When can you complete it?  The above email is from April.

Having gone back through this thread (again) to figure out where we are
on this, and chatting with Jonathan about the options that are available
through the web system, and trying to sort out my own feelings on what
makes the most sense here, I'd like to bring up a few points and a
proposal regarding the rename:

- General agreement that 'predefined' is better than 'default'
- Unclear on back-patching:
  Voices in favor: Rob, Laurenz, Bruce
  Voices against: Ian, Simon, Peter, Stephen

Having understood now a bit better what is possible with the web system,
many thanks to Jonathan for chatting with me about it, I'll try to
explain here what the options are:

- Change the back-branches and use the new feature ("doc page
  redirects") to redirect old links to default-roles to
  predefined-roles.

- Change the feature's name in v14, but create a "doc page alias" to
  allow users viewing v13's "default roles" to see a v14 link which
  would take them to "predefined roles".

I'll note that we've got a number of examples of "doc page aliases"
being used to handle name changes:

    catalog-pg-replication-slots.html <-> view-pg-replication-slots.html
    pgxlogdump.html <-> pgwaldump.html
    app-pgresetxlog.html <-> app-pgresetwal.html
    legalnotice.html <-> LEGALNOTICE.html
    app-pgreceivexlog.html <-> app-pgreceivewal.html

I've also been thinking about the code change impact from this, as I do
think we should have the code and the documentation and general feature
naming be consistent, but that implies changing things like
DEFAULT_ROLE_MONITOR to be PREDEFINED_ROLE_MONITOR, potentially breaking
compilation of extensions that use those #define's (such as even our own
extensions like file_fdw do) in a minor version update, which doesn't
seem terribly nice to do.

Therefore, on the whole, the proposal that I would put out there is:

- Rename everything (code, docs, etc) to 'predefined roles' for v14+
- Update the documentation (only) in back-branches to mention that the
  feature was renamed in v14 to 'predefined roles'
- Use the 'doc page alias' feature to make the documentation page for
  'default roles' on the older versions link to 'predefined roles' in
  the newer versions, and vice-versa

Thoughts?

Thanks,

Stephen

On Fri, Oct 23, 2020 at 05:40:37PM -0400, Stephen Frost wrote:
> Therefore, on the whole, the proposal that I would put out there is:
> 
> - Rename everything (code, docs, etc) to 'predefined roles' for v14+
> - Update the documentation (only) in back-branches to mention that the
>   feature was renamed in v14 to 'predefined roles'
> - Use the 'doc page alias' feature to make the documentation page for
>   'default roles' on the older versions link to 'predefined roles' in
>   the newer versions, and vice-versa

Sure, that works for me.  If it was only docs, backpatch makes more
sense, but once you showed the renaming in those other areas,
master-only makes more sense.  Thanks for working on this.

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

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

Greetings,

* Bruce Momjian (bruce@momjian.us) wrote:
> On Fri, Oct 23, 2020 at 05:40:37PM -0400, Stephen Frost wrote:
> > Therefore, on the whole, the proposal that I would put out there is:
> >
> > - Rename everything (code, docs, etc) to 'predefined roles' for v14+
> > - Update the documentation (only) in back-branches to mention that the
> >   feature was renamed in v14 to 'predefined roles'
> > - Use the 'doc page alias' feature to make the documentation page for
> >   'default roles' on the older versions link to 'predefined roles' in
> >   the newer versions, and vice-versa
>
> Sure, that works for me.  If it was only docs, backpatch makes more
> sense, but once you showed the renaming in those other areas,
> master-only makes more sense.  Thanks for working on this.

I've written a patch to begin to make this change and sent it into
-hackers for comments, thread is here:

https://postgr.es/m/20201120211304.GG16415@tamriel.snowman.net

Naturally, it won't make sense to make a change to the back branches
until the change has been agreed to and committed for v14.

Thanks,

Stephen

Greetings,

* Stephen Frost (sfrost@snowman.net) wrote:
> * Bruce Momjian (bruce@momjian.us) wrote:
> > On Fri, Oct 23, 2020 at 05:40:37PM -0400, Stephen Frost wrote:
> > > Therefore, on the whole, the proposal that I would put out there is:
> > >
> > > - Rename everything (code, docs, etc) to 'predefined roles' for v14+
> > > - Update the documentation (only) in back-branches to mention that the
> > >   feature was renamed in v14 to 'predefined roles'
> > > - Use the 'doc page alias' feature to make the documentation page for
> > >   'default roles' on the older versions link to 'predefined roles' in
> > >   the newer versions, and vice-versa
> >
> > Sure, that works for me.  If it was only docs, backpatch makes more
> > sense, but once you showed the renaming in those other areas,
> > master-only makes more sense.  Thanks for working on this.
>
> I've written a patch to begin to make this change and sent it into
> -hackers for comments, thread is here:
>
> https://postgr.es/m/20201120211304.GG16415@tamriel.snowman.net

Just to wrap this up- this change has now been committed for v14.

Thanks,

Stephen

On 4/1/21 3:34 PM, Stephen Frost wrote:
> Greetings,
>
> * Stephen Frost (sfrost@snowman.net) wrote:

>> I've written a patch to begin to make this change and sent it into
>> -hackers for comments, thread is here:
>>
>> https://postgr.es/m/20201120211304.GG16415@tamriel.snowman.net
>
> Just to wrap this up- this change has now been committed for v14.

Thanks Stephen! Do we have any additional follow up on the pgweb side?

Thanks,

Jonathan

Greetings,

* Jonathan S. Katz (jkatz@postgresql.org) wrote:
> On 4/1/21 3:34 PM, Stephen Frost wrote:
> > * Stephen Frost (sfrost@snowman.net) wrote:
>
> >> I've written a patch to begin to make this change and sent it into
> >> -hackers for comments, thread is here:
> >>
> >> https://postgr.es/m/20201120211304.GG16415@tamriel.snowman.net
> >
> > Just to wrap this up- this change has now been committed for v14.
>
> Thanks Stephen! Do we have any additional follow up on the pgweb side?

Yes and no. :)

Once the next set of minor releases is pushed out, I'll double-check
that everything is working properly (the 'obsolete' pages should start
showing up instead of the redirects, since we'll no longer be going
through the "page not found" code path) and will then go remove the
alias/redirects from the pages that no longer need them.

Thanks!

Stephen

On 4/2/21 9:11 AM, Stephen Frost wrote:
> Greetings,
>
> * Jonathan S. Katz (jkatz@postgresql.org) wrote:

>> Thanks Stephen! Do we have any additional follow up on the pgweb side?
>
> Yes and no. :)
>
> Once the next set of minor releases is pushed out, I'll double-check
> that everything is working properly (the 'obsolete' pages should start
> showing up instead of the redirects, since we'll no longer be going
> through the "page not found" code path) and will then go remove the
> alias/redirects from the pages that no longer need them.

Great -- thanks for confirming.

Thanks,

Jonathan