Description of the need

When I see that a certain permission "has security implications", I wonder what those implications are, and how much they'll affect my site/users...

Proposed solution

I'd like to propose allowing developers to write an additional description for permissions that describe what the security implications are.

Alternatives that have been considered

Backdrop already has this ability, with the warning key of hook_permission(). However, it says:

This warning overrides the automatic warning generated by 'restrict access' being set to TRUE. This should rarely be used, since it is important for all permissions to have a clear, consistent security warning that is the same across the site.

Additional information

I therefore propose re-purposing this warning key to allow providing an additional description. That way, the security warning (based on the restrict access key) remains clear and consistent, but more information can be provided if/as necessary.

I've looked through all core implementations of hook_permission(), and nowhere is this used. The only place that almost uses it is the Filter module, but it adds its own emphasised warning description, rather than utilising the dedicated 'warning' key.

Semi-related issue:

Draft of feature description for Press Release (1 paragraph at most)

Backdrop now displays permission warning descriptions separately to the default security warning message. This allows for more consistent messaging and the ability to better describe why certain permissions have security implications.

GitHub Issue #: