Re: debconfig-common new template text review
Rafael David Tinoco wrote:
> I'm proposing a change to debconfig-common in the following merge request:
>
> https://salsa.debian.org/debian/dbconfig-common/merge_requests/3
>
> And Paul Gevers, reviewing it, thought it was better to review the
> template text before accepting the merge. With that, would you mind
> reviewing the text bellow and checking if there is anything that could
> be more clear to the end user ?
Yes, this needs some work.
(By the way, what are the "~" lines? Is this some git-diffism that
I'm not familiar with?)
> """
>
> Template: dbconfig-common/mysql/authplugin
> Type: select
> __Choices: default, mysql_native_password, sha256_password, caching_sha2_password
> Default: default
> _Description: Authentication plugin for MySQL database:
> ~ This option defines the MySQL authentication plugin to be used when
^^^^^^^^^^^^^^^^^^^
"This option" doesn't work here - partly because there's nothing for
"this" to refer to and partly because it seems to be misusing "option"
(options are candidates for selection, not opportunities to select).
The recommended wording for a "select" prompt is something like:
Please specify the MySQL authentication plugin that should be used when
> ~ creating new users through dbconfig-common. Most of the times, default
^^^^^^^^ ^ ^
It's not clear what's doing the creating of new users here, Could we
simplify it to the following?
dbconfig-common creates new users. Most of the time, the default option
(also fixing a couple of idioms in passing)
> + will be enough, and will not specify a particular plugin, letting
Grammar trouble - you've got "default" as the subject of "will not
specify". What you're trying to say is that the default is for
db-config not to specify a plugin, in which case we want
of leaving the plugin unspecified will work, letting
> + MySQL to chose its default authentication plugin. Some dbconfig-common
^^ ^
Excess "to", and you've run into a spelling boobytrap.
MySQL choose its default authentication plugin. Some dbconfig-common
> + consumers might change the default because of compatibility reasons.
I assume by "consumers" it means db-using packages, not (directly)
users.
Slightly more idiomatic:
consumers might change the default for compatibility reasons.
But it's not clear what this means by "compatibility", Should it
perhaps be saying something like this?
Please specify the MySQL authentication plugin that should be used when
dbconfig-common creates new users. Most of the time, the default option
of leaving the plugin unspecified will work - this lets MySQL choose
the authentication plugin, which may vary for particular
dbconfig-common consumers.
> .
> ~ - default: MySQL will use its default authentication plugin.
> .
> - mysql_native_password: no MySQL authentication plugin is used.
> .
> - sha256_password: a more secure password encryption than native.
> .
> - caching_sha2_password: provides in-memory authentication cache.
>
> """
You seem to be confusing "Choices" (raw debconf-internal option names)
with "__Choices" (internationalisable labels for these options). And
starting lines with an unindented dash won't turn this into a bulleted
list; what you want is something like
Choices: default, mysql_native_password, sha256_password, caching_sha2_password
__Choices: default, native, SHA256, caching
[...]
.
* default: MySQL will use its default authentication plugin;
* native: no MySQL authentication plugin is used;
* SHA256: a more secure password encryption than native;
* caching: SHA2 plus an in-memory authentication cache.
But from the explanation, I'm not sure it's accurate to say that
leaving it set to the default of "default" will tell MySQL to "use its
default authentication plugin" (apparently, SHA2 without caching).
Surely the whole point is that it doesn't impose any such choice?
Yes, if nothing else expresses a preference then MySQL will default to
whatever its default is, but surely that's the definition of default,
and doesn't need to be explained here!
In which case I'd expect it to say something more like this:
Template: dbconfig-common/mysql/authplugin
Type: select
Choices: default, mysql_native_password, sha256_password, caching_sha2_password
__Choices: unspecified, native, SHA256, caching
Default: default
_Description: Authentication plugin for MySQL database:
Please specify whether a specific MySQL authentication plugin should
always be used when dbconfig-common creates new users. Most of the time,
the default option of leaving the plugin unspecified will work - this
allows the choice to vary for particular dbconfig-common consumers.
.
* unspecified: let db-config consumers override the default;
* native: no MySQL authentication plugin is used;
* SHA256: a more secure password encryption algorithm;
* caching: SHA2 plus an in-memory authentication cache.
(It's a while since I reviewed a template with __Choices, so apologies
if I'm forgetting the details of the syntax.)
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: