Subject: Re: Documentation: 21.5. Default Roles
To: R Ransbottom <rirans@comcast.net>, Stephen Frost <sfrost@snowman.net>
Cc: Bruce Momjian <bruce@momjian.us>, Laurenz Albe
 <laurenz.albe@cybertec.at>, pgsql-docs@lists.postgresql.org
References: <157742545062.1149.11052653770497832538@wrigleys.postgresql.org>
 <20191227171654.GA2992@momjian.us>
 <8c2f4f1b90c993c8c6338b978a78a9ebbcd1c934.camel@cybertec.at>
 <20200114181331.GB10430@momjian.us>
 <20200114194502.GX3195@tamriel.snowman.net>
 <20200119035648.3k4d3erobborxwv3@rat.local>
From: Ian Barwick <ian.barwick@2ndquadrant.com>
Message-ID: <957c35e3-8023-ebe6-3b51-3a620b66ae82@2ndquadrant.com>
Date: Mon, 20 Jan 2020 12:23:48 +0900
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101
 Thunderbird/68.3.0
MIME-Version: 1.0
In-Reply-To: <20200119035648.3k4d3erobborxwv3@rat.local>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Precedence: bulk

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