Re: Documentation: 21.5. Default Roles

[Jonathan S. Katz]

On 4/2/21 9:11 AM, Stephen Frost wrote:
> Greetings,
> 
> * Jonathan S. Katz (jk...@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



OpenPGP_signature
Description: OpenPGP digital signature

Re: Documentation: 21.5. Default Roles

[Stephen Frost]

Greetings,

* Jonathan S. Katz (jk...@postgresql.org) wrote:
> On 4/1/21 3:34 PM, Stephen Frost wrote:
> > * Stephen Frost (sfr...@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.gg16...@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


signature.asc
Description: PGP signature

Re: Documentation: 21.5. Default Roles

[Jonathan S. Katz]

On 4/1/21 3:34 PM, Stephen Frost wrote:
> Greetings,
> 
> * Stephen Frost (sfr...@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.gg16...@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



OpenPGP_signature
Description: OpenPGP digital signature

Re: Documentation: 21.5. Default Roles

[Stephen Frost]

Greetings,

* Stephen Frost (sfr...@snowman.net) wrote:
> * Bruce Momjian (br...@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.gg16...@tamriel.snowman.net

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

Thanks,

Stephen


signature.asc
Description: PGP signature

Re: Documentation: 21.5. Default Roles

[Stephen Frost]

Greetings,

* Bruce Momjian (br...@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.gg16...@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


signature.asc
Description: PGP signature

Re: Documentation: 21.5. Default Roles

[Bruce Momjian]

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  https://momjian.us
  EnterpriseDB https://enterprisedb.com

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

Re: Documentation: 21.5. Default Roles

[Stephen Frost]

Greetings,

* Bruce Momjian (br...@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


signature.asc
Description: PGP signature

Re: Documentation: 21.5. Default Roles

[Bruce Momjian]

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  > > 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  https://momjian.us
  EnterpriseDB https://enterprisedb.com

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

Re: Documentation: 21.5. Default Roles

[Peter Eisentraut]

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

Re: Documentation: 21.5. Default Roles

[Jonathan S. Katz]

On 4/28/20 2:19 PM, Magnus Hagander wrote:
> On Sat, Apr 25, 2020 at 1:38 AM Jonathan S. Katz  > 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



signature.asc
Description: OpenPGP digital signature

Re: Documentation: 21.5. Default Roles

[Magnus Hagander]

On Tue, Apr 28, 2020 at 8:20 PM Stephen Frost  wrote:

> Greetings,
>
> * Magnus Hagander (mag...@hagander.net) wrote:
> > On Sat, Apr 25, 2020 at 1:38 AM Jonathan S. Katz 
> > 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?
>
>
GIven how seldom this happens, I think that's perfectly fine. Same as we
already do with the page aliases.

//Magnus

Re: Documentation: 21.5. Default Roles

[Stephen Frost]

Greetings,

* Magnus Hagander (mag...@hagander.net) wrote:
> On Sat, Apr 25, 2020 at 1:38 AM Jonathan S. Katz 
> 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


signature.asc
Description: PGP signature

Re: Documentation: 21.5. Default Roles

[Magnus Hagander]

On Sat, Apr 25, 2020 at 1:38 AM Jonathan S. Katz 
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.

//Magnus

Re: Documentation: 21.5. Default Roles

[Jonathan S. Katz]

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
From e2120f0a80697d13dc6d951f363d01feb60c9b9d Mon Sep 17 00:00:00 2001
From: "Jonathan S. Katz" 
Date: Tue, 11 Feb 2020 14:41:46 -0500
Subject: [PATCH] Introduce documentation redirects for doc pages that are
 renamed

The web documentation used to suffer from a problem that if a
documentation page were renamed in a newer version, any references
pointing to said documentation would be lost. For example, the feature
known as "Default Roles" was renamed to "Privileged Roles" but caused
a change in the URL.

This patch introduces the ability to create a "DocPageRedirect" by
specifying the previous name of the documentation page (e.g.
"default-roles.html") and the new name (e.g. "privileged-roles.html")
such that the continuity is preserved between versions.
---
 pgweb/docs/admin.py   |  3 ++-
 pgweb/docs/migrations/0004_docpageredirect.py | 24 +++
 pgweb/docs/models.py  | 11 +
 pgweb/docs/views.py   | 15 ++--
 4 files changed, 50 insertions(+), 3 deletions(-)
 create mode 100644 pgweb/docs/migrations/0004_docpageredirect.py

diff --git a/pgweb/docs/admin.py b/pgweb/docs/admin.py
index d2f2590..79f1d12 100644
--- a/pgweb/docs/admin.py
+++ b/pgweb/docs/admin.py
@@ -1,5 +1,6 @@
 from django.contrib import admin
 
-from .models import DocPageAlias
+from .models import DocPageAlias, DocPageRedirect
 
 admin.site.register(DocPageAlias)
+admin.site.register(DocPageRedirect)
diff --git a/pgweb/docs/migrations/0004_docpageredirect.py 
b/pgweb/docs/migrations/0004_docpageredirect.py
new file mode 100644
index 000..d19f959
--- /dev/null
+++ b/pgweb/docs/migrations/0004_docpageredirect.py
@@ -0,0 +1,24 @@
+# Generated by Django 2.2.12 on 2020-04-24 23:16
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+dependencies = [
+('docs', '0003_docs_alias'),
+]
+
+operations = [
+migrations.CreateModel(
+name='DocPageRedirect',
+fields=[
+('id', models.AutoField(auto_created=True, primary_key=True, 
serialize=False, verbose_name='ID')),
+('redirect_from', models.CharField(max_length=64, unique=True, 
help_text='Page to redirect from, e.g. "old_page.html"')),
+('redirect_to', models.CharField(max_length=64, unique=True, 
help_text='Page to redirect to, e.g. "new_page.html"')),
+],
+options={
+'verbose_name_plural': 'Doc page redirects',
+},
+),
+]
diff --git a/pgweb/docs/models.py b/pgweb/docs/models.py
index 87afe1c..a4558a6 100644
--- a/pgweb/docs/models.py
+++ b/pgweb/docs/models.py
@@ -33,3 +33,14 @@ class DocPageAlias(models.Model):
 class Meta:
 db_table = 'docsalias'
 verbose_name_plural = 'Doc page aliases'
+
+
+class DocPageRedirect(models.Model):
+"""DocPageRedirect offers the ability to redirect from a page that has been
+completely removed from the PostgreSQL documentation
+"""
+redirect_from = models.CharField(max_length=64, null=False, blank=False, 
unique=True, help_text='Page to redirect from, e.g. "old_page.html"')
+redirect_to = models.CharField(max_length=64, null=False, blank=False, 
unique=True, help_text='Page to redirect from, e.g. "new_page.html"')
+
+class Meta:
+verbose_name_plural = "Doc page redirects"
diff --git a/pgweb/docs/views.py b/pgweb/docs/views.py
index 0566129..6763795 100644
--- a/pgweb/docs/views.py
+++ b/pgweb/docs/views.py
@@ -16,7 +16,7 @@ from pgweb.util.misc import send_template_mail
 from pgweb.core.models import Version
 from pgweb.util.db import exec_to_dict
 
-from .models import DocPage
+from .models import DocPage, DocPageRedirect
 from .forms import DocCommentForm
 
 
@@ -94,7 +94,18 @@ def docpage(request, version, filename):
 url += "{}/{}".format(release_version, fullname)
 

Re: Documentation: 21.5. Default Roles

[Bruce Momjian]

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  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 +

Re: Documentation: 21.5. Default Roles

[Jonathan S. Katz]

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



signature.asc
Description: OpenPGP digital signature

Re: Documentation: 21.5. Default Roles

[Bruce Momjian]

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  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 +

Re: Documentation: 21.5. Default Roles

[Stephen Frost]

Greetings,

On Sun, Feb 9, 2020 at 14:24 Tom Lane  wrote:

> Stephen Frost  writes:
> > * Jonathan S. Katz (jk...@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.


Ah, thanks, Friday got away from me and it’s been a busy weekend, I had
figured on tonight but glad you took care of it.

Thanks again,

Stephen

>

Re: Documentation: 21.5. Default Roles

[Tom Lane]

Stephen Frost  writes:
> * Jonathan S. Katz (jk...@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

Re: Documentation: 21.5. Default Roles

[Bruce Momjian]

On Thu, Feb  6, 2020 at 11:05:04AM -0500, Stephen Frost wrote:
> * Jonathan S. Katz (jk...@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  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 +

Re: Documentation: 21.5. Default Roles

[Stephen Frost]

Greetings,

* Jonathan S. Katz (jk...@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


signature.asc
Description: PGP signature

Re: Documentation: 21.5. Default Roles

[Jonathan S. Katz]

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



signature.asc
Description: OpenPGP digital signature

Re: Documentation: 21.5. Default Roles

[Bruce Momjian]

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  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 +

Re: Documentation: 21.5. Default Roles

[Jonathan S. Katz]

On 2/4/20 3:34 AM, Magnus Hagander wrote:
> On Mon, Feb 3, 2020 at 9:59 PM 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.
> 
> 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



signature.asc
Description: OpenPGP digital signature

Re: Documentation: 21.5. Default Roles

[Stephen Frost]

Greetings,

* Alvaro Herrera (alvhe...@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 -- 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


signature.asc
Description: PGP signature

Re: Documentation: 21.5. Default Roles

[Magnus Hagander]

On Mon, Feb 3, 2020 at 9:59 PM Jonathan S. Katz  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/

Re: Documentation: 21.5. Default Roles

[Alvaro Herrera]

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 -- to the effect that feature-X used to be
called feature-Y, immediately following the section title.

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

Re: Documentation: 21.5. Default Roles

[Jonathan S. Katz]

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
Description: OpenPGP digital signature

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  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 +

Re: Documentation: 21.5. Default Roles

[R Ransbottom]

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

Re: Documentation: 21.5. Default Roles

[Tom Lane]

Bruce Momjian  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,  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

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  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 +

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

Re: Documentation: 21.5. Default Roles

[Bruce Momjian]

On Mon, Jan 20, 2020 at 06:45:16PM +, Simon Riggs wrote:
> On Mon, 20 Jan 2020 at 16:03, Bruce Momjian  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  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 +

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  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 +

Re: Documentation: 21.5. Default Roles

[Ian Barwick]

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 (br...@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 +, 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

Re: Documentation: 21.5. Default Roles

[R Ransbottom]

Hi,

On Tue, Jan 14, 2020 at 02:45:02PM -0500, Stephen Frost wrote:
> * Bruce Momjian (br...@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 +, 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

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  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 +

Re: Documentation: 21.5. Default Roles

[Stephen Frost]

Greetings,

* Bruce Momjian (br...@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 +, 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
Description: PGP signature

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 +, 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  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 +

Re: Documentation: 21.5. Default Roles

[Laurenz Albe]

On Fri, 2019-12-27 at 12:16 -0500, Bruce Momjian wrote:
> On Fri, Dec 27, 2019 at 05:44:10AM +, 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

Re: Documentation: 21.5. Default Roles

[Bruce Momjian]

On Fri, Dec 27, 2019 at 05:44:10AM +, 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  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 +
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index dcb58115af..136778cb8a 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -277,7 +277,7 @@ postgres   27093  0.0  0.0  30096  2752 ?Ss   11:34   0:00 postgres: ser
existence of a session and its general properties such as its sessions user
and database are visible to all users.  Superusers and members of the
built-in role pg_read_all_stats (see also ) can see all the information about all sessions.
+   linkend="predefined-roles"/>) can see all the information about all sessions.
   
 
   
diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index 66f162703d..4432ee266b 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -483,30 +483,30 @@ DROP ROLE doomed_role;
   
  
 
- 
-  Default Roles
+ 
+  Predefined Roles
 
-  
+  
role
   
 
   
-   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.
+   PostgreSQL provides a set of predefined
+   roles which allow access to privileged capabilities and information.
+   Administrators can GRANT these roles to login and non-login roles,
+   providing those roles with access to the specified capabilities and
+   information.
   
 
   
-   The default roles are described in .
-   Note that the specific permissions for each of the default roles may
+   The predefined roles are described in .
+   Note that the specific permissions for each of the predefined roles may
change in the future as additional capabilities are added.  Administrators
should monitor the release notes for changes.
   
 
-   
-Default Roles
+   
+Predefined Roles
 
  
   
@@ -565,8 +565,8 @@ DROP ROLE doomed_role;
   pg_read_all_stats and pg_stat_scan_tables
   roles are intended to allow administrators to easily configure a role for the
   purpose of monitoring the database server. They grant a set of common privileges
-  allowing the role to read various useful configuration settings, statistics and
-  other system information normally restricted to superusers.
+  allowing the role to read configuration settings, statistics, and other
+  system information normally restricted to superusers.
   
 
   

Documentation: 21.5. Default Roles

[PG Doc comments 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.