4487 was the trigger for this issue here.

Our Drupal brethren started implementing this and were originally planning to add it in Drupal 8.5.0:

• Change record (draft): Permissions may be marked deprecated in the permission definition
• Issue (still open - now against Drupal 9.2.x): https://www.drupal.org/project/drupal/issues/2924785

Problem/Motivation

Wherever possible, Drupal 8 code should deprecate instead of removing old code, behaviors, etc.

Permission machine names are stored in user role configurations, but they are also used in code for many things like access checks. This means that if core updates the machine name of a permission, even if it provides an upgrade path, contributed module code that checks against the core permissions might start to deny access that should be allowed.

Marked major because it affects how thoroughly we can implement our backwards compatibility policy.

Proposed resolution

Provide a mechanism to deprecate permissions in the permission definition.

Remaining tasks

• Needs review.
• Followup to explore how to raise warnings when a deprecated permission is used.

User interface changes

If no deprecated permissions are used, there is no UI change: unused deprecated permissions are simply not presented to the user.

If a deprecated permission is in use, the user will see a short message under the permission. The permission can be revoked from roles that have it through the UI, but not granted to additional roles (unchecked checkboxes for it will be disabled).

A message will also be provided on the status report.

API changes

A deprecated key is added to the permission definition API.