Plugins can be declared deprecated

Plugins can now be deprecated. Methods are added to check for the deprecation when a plugin is constructed, to determine if a plugin is deprecated and to get the deprecation messaged.

Deprecate a plugin defined in a class

Add a property 'deprecationMessage' with the deprecation message.
For example.

  /**
   * Deprecation message.
   * 
   * @var string
   */
  protected $deprecationMessage = 'the deprecation message'

Deprecate a plugin defined by an array

Add a property 'deprecation_message' with the deprecation message as the value.

For example, for a migration plugin defined in a YAML file,

id: d7_custom_node
label: Custom node migration
deprecation_message: core/modules/migrate/tests/modules/migrate_deprecate_test/migrations/deprecated.yml is deprecated in drupal:9.2.0 and is removed from drupal:10.0.0. Use core/modules/migrate/tests/modules/migrate_deprecate_test/migrations/new.yml instead. See https://www.drupal.org/node/3039240

Trigger a deprecation message when the plugin is constructed

Add \Drupal\Component\Plugin\PluginInspectionTrait::checkDeprecation() to the constructor.
For example,

  public function __construct(array $configuration, $plugin_id, $plugin_definition) {
    $this->configuration = $configuration;
    $this->pluginId = $plugin_id;
    $this->pluginDefinition = $plugin_definition;
    $this->checkDeprecation();
  }

Find out if an existing plugin is deprecated

For example,
$plugin_instance->isDeprecated()

Get the deprecation message for an existing plugin

For example,
$plugin_instance->getDeprecationMessage()