Re: Documentation: 21.5. Default Roles

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

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

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

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

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

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

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

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