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: The "%permission%" permission is deprecated in drupal:12.0.0 and is removed from drupal:12.1.0. Use the bundle-specific "update any $type media" permissions instead.

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