Documentation: 21.5. Default Roles

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

Documentation: 21.5. Default Roles

PG Bug reporting form
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.
Reply | Threaded
Open this post in threaded view
|

Re: Documentation: 21.5. Default Roles

Bruce Momjian
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  <[hidden email]>        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 +

roles.diff (3K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Documentation: 21.5. Default Roles

Stephen Frost
In reply to this post by PG Bug reporting form
Greetings,

* PG Doc comments form ([hidden email]) 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

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

Re: Documentation: 21.5. Default Roles

Laurenz Albe
In reply to this post by Bruce Momjian
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



Reply | Threaded
Open this post in threaded view
|

Re: Documentation: 21.5. Default Roles

Bruce Momjian
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  <[hidden email]>        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 +


Reply | Threaded
Open this post in threaded view
|

Re: Documentation: 21.5. Default Roles

Stephen Frost
Greetings,

* Bruce Momjian ([hidden email]) 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

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

Re: Documentation: 21.5. Default Roles

Bruce Momjian
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  <[hidden email]>        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 +


Reply | Threaded
Open this post in threaded view
|

Re: Documentation: 21.5. Default Roles

R Ransbottom
In reply to this post by Stephen Frost
Hi,

On Tue, Jan 14, 2020 at 02:45:02PM -0500, Stephen Frost wrote:

> * Bruce Momjian ([hidden email]) 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





Reply | Threaded
Open this post in threaded view
|

Re: Documentation: 21.5. Default Roles

Ian Barwick-3
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 ([hidden email]) 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


Reply | Threaded
Open this post in threaded view
|

Re: Documentation: 21.5. Default Roles

Bruce Momjian
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  <[hidden email]>        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 +


Reply | Threaded
Open this post in threaded view
|

Re: Documentation: 21.5. Default Roles

Simon Riggs
On Mon, 20 Jan 2020 at 16:03, Bruce Momjian <[hidden email]> wrote:
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.

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.

--
Simon Riggs                http://www.2ndQuadrant.com/
PostgreSQL Solutions for the Enterprise
Reply | Threaded
Open this post in threaded view
|

Re: Documentation: 21.5. Default Roles

Bruce Momjian
On Mon, Jan 20, 2020 at 06:45:16PM +0000, Simon Riggs wrote:

> On Mon, 20 Jan 2020 at 16:03, Bruce Momjian <[hidden email]> 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  <[hidden email]>        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 +


Reply | Threaded
Open this post in threaded view
|

Re: Documentation: 21.5. Default Roles

Laurenz Albe
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



Reply | Threaded
Open this post in threaded view
|

Re: Documentation: 21.5. Default Roles

Bruce Momjian
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  <[hidden email]>        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 +


Reply | Threaded
Open this post in threaded view
|

Re: Documentation: 21.5. Default Roles

Tom Lane-2
Bruce Momjian <[hidden email]> 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


Reply | Threaded
Open this post in threaded view
|

Re: Documentation: 21.5. Default Roles

R Ransbottom
In reply to this post by Ian Barwick-3
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


Reply | Threaded
Open this post in threaded view
|

Re: Documentation: 21.5. Default Roles

Bruce Momjian
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  <[hidden email]>        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 +


Reply | Threaded
Open this post in threaded view
|

Re: Documentation: 21.5. Default Roles

Jonathan S. Katz-3
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


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

Re: Documentation: 21.5. Default Roles

Alvaro Herrera-9
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


Reply | Threaded
Open this post in threaded view
|

Re: Documentation: 21.5. Default Roles

Magnus Hagander-2
In reply to this post by Jonathan S. Katz-3
On Mon, Feb 3, 2020 at 9:59 PM Jonathan S. Katz <[hidden email]> 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/


12