Date: Fri, 23 Oct 2020 17:40:37 -0400
From: Stephen Frost <sfrost@snowman.net>
To: Bruce Momjian <bruce@momjian.us>
Cc: "Jonathan S. Katz" <jkatz@postgresql.org>,
	Magnus Hagander <magnus@hagander.net>,
	R Ransbottom <rirans@comcast.net>,
	Ian Barwick <ian.barwick@2ndquadrant.com>,
	Laurenz Albe <laurenz.albe@cybertec.at>,
	Pg Docs <pgsql-docs@lists.postgresql.org>
Subject: Re: Documentation: 21.5. Default Roles
Message-ID: <20201023214037.GS16415@tamriel.snowman.net>
References: <5982a365-a38a-f81a-003c-f72cb4d7f269@postgresql.org>
 <20200206051131.GA20009@momjian.us>
 <41fb663f-96e5-dece-8aba-97d16f395948@postgresql.org>
 <20200409205716.GB26811@momjian.us>
 <eaf0a37d-c92e-3770-b5ec-1ab129dd9185@postgresql.org>
 <20200410034523.GA26824@momjian.us>
 <4490e710-85f7-87a9-74dd-793d27440bed@postgresql.org>
 <CABUevEwYMVbqMi7fe7n40PeFtj0meNjpP4rx=HwJO8Ef8kj75g@mail.gmail.com>
 <40cafc51-1235-ee8a-dd24-075618361c50@postgresql.org>
 <20201005203112.GD4993@momjian.us>
MIME-Version: 1.0
Content-Type: multipart/signed; micalg=pgp-sha512;
	protocol="application/pgp-signature"; boundary="vy3x0i7GCC7mAH4A"
Content-Disposition: inline
In-Reply-To: <20201005203112.GD4993@momjian.us>
User-Agent: Mutt/1.5.24 (2015-08-30)
Precedence: bulk


--vy3x0i7GCC7mAH4A
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

Greetings,

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

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

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

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

--vy3x0i7GCC7mAH4A
Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1

iQIcBAEBCgAGBQJfk03UAAoJEO1sijiDR2RVGe0P/1rYTNJordMjyu859DD8o1mo
O5ItMZt95aLKUjqbJYT5/xBYeYQtus6R2FvDvmHyis8mpfeykl0FQaZDnfkt885G
DniPfmHtBMQnjPqZ1JKu8yNDdT3Ij4wpfSGhWTfnRcNipGV5ow7iauOfi3h4e7Yx
4XPgWiFhX3qBmOQjKpyXOj1MKShoOxfTa48XxI+LhMaUsyszQqZ7FGlAQXTm7Fuo
2G2AlLn1rSLYbRDsswxIEckTimZq7OHYX1LKKFFLDBwN71shuSQUK+xoJDL2p5EE
A6Xxsqiq2ZVQFsaMQ4uvsi2z0SAMsuDao2wScEMkWpD2P7Wgut2Sl/eNRkgeedeT
hzWwQwJ/6Aldnq6CUzGgFmIm1t243DOFOynXiQcONk+zrPoVkl5XG7hm+wRG//Fa
KUEwgdhaW2z+h/XcIy8oVpzqzr2MvOYDB+6Oi5W2HRwKLY8WacJqUg0s/xMDg035
M0zY4OpPNEESfeoLqL5q0F9PDF39jv0ZMBOcPDcPQmgSHyY9yMV23zjb+KptxhUQ
X/ftT/bnsPCfoxJFnMiZGT2fCboJQrNkRWMh/y9PjsqgcJ5FL15OLOGLc/WrHcpM
ws9v28+vvEBc48hcO1ZUWb993SuBONmPNEGfvLeY2P/xOLSPJBMpIzsdN10aTZR1
wDt0Nu1by8jty6L1FbqT
=hhIj
-----END PGP SIGNATURE-----

--vy3x0i7GCC7mAH4A--