Permissions may be marked deprecated in the permission definition

Permission machine names are stored in role configurations, but they are also a public API since it is common to add customized access checks or use existing permissions to control access to added functionality. For this reason, permission machine names should not be changed or removed within a major version.

In order to allow permission changes with backwards compatibility, a new 'deprecated' key has been added to permission definitions. (See PermissionHandlerInterface for more information on permission definitions.)

To deprecate a permission, a module must do two things:

1. Mark the permission as deprecated in its *.permissions.yml file:
   

   update any media:
     title: 'Update any media'
     # @deprecated as of Drupal 8.5.x and will be removed before 9.0.0. Use the
     # bundle-specific "update any $type media" permissions instead.
     deprecated: true

2. Provide an upgrade path to update roles to change permissions as appropriate.

Deprecated permissions will only be displayed in the permissions user interface of they are still assigned to a given role.