Introduce a way to deprecate config schemas

For what it's worth I think this patch is great. Great idea to put this in the schema checker! Could use some more eyes before RTBC, though.

+++ b/core/tests/Drupal/KernelTests/Core/Config/SchemaCheckTraitTest.php
@@ -39,6 +40,8 @@ protected function setUp() {
+   * @expectedDeprecationMessage The 'complex_structure' config schema is deprecated in Drupal 8.7.x and will be removed in Drupal 9.0.x. Use the 'complex' config schema instead. See http://drupal.org/node/the-change-notice-nid.

Isn't this just @expectedDeprecation? I see two other uses of @expectedDeprecationMessage in core but don't see where this is actually handled.

Recategorized as Task, as we clearly need a mechanism to deprecate config schemata.

Re @expectedDeprecationMessage:
#2928645: \Drupal\Tests\migrate\Kernel\Plugin\MigrationDirectoryTest uses @expectedDeprecationMessage has a bit more on this. However, if @expectedDeprecationMessage really does nothing, then #2 should fail with the CI, shouldn't it?

Is this still feasible before 9.0.0?

I think we need this, and the proposal looks great.

During the 8.x lifecycle, has this even happened in core?
If it did, we would need a way to identify those and create child issues for deprecating them.

Tagging as Needs product manager review, as I guess it does.

This doesn't need product manager review, it's just an API addition.

Would need to go into 9.1.x at this point. I kicked off a test against 9.1.x

Would be good to know if we have a use-case per #14.

+++ b/core/tests/Drupal/KernelTests/Core/Config/ConfigInstallTest.php
@@ -11,6 +11,8 @@
+ * @group legacy
+ *

+++ b/core/tests/Drupal/KernelTests/Core/Config/ConfigSchemaTest.php
@@ -17,6 +17,7 @@
+ * @group legacy

+++ b/core/tests/Drupal/KernelTests/Core/Config/SchemaCheckTraitTest.php
@@ -9,6 +9,7 @@
+ * @group legacy

Marking the whole test as legacy is wrong. We should not put config_schema_test.deprecated in install config. We should only create it in a specific legacy test.

The implementation looks fine. ONe thing I'm trying to work out is why you'd deprecate schema and not the config value itself... And once you've deprecated a specific config value what's the point of deprecating its schema? OTOH this might provide a nice way to deprecate config values and only have to add something to schema...

@claudiu.cristea how does that actually work though? If the config is the same with the same keys then we can't have a deprecated schema pointing to a non-deprecated config value.

Ah I see that issue suggests we need to deprecate a type tat might be used in many places...looking at that issue I'm not convinced it's the way to go. But I guess the use-case makes some sense.

It's best to not make the a module provide deprecated config.

1. +++ b/core/tests/Drupal/KernelTests/Core/Config/ConfigSchemaDeprecationTest.php
   @@ -0,0 +1,33 @@
   +    $this->installConfig(['config_schema_deprecated_test']);
   

   Instead of installing config here we can write the configuration.

2. +++ b/core/tests/Drupal/KernelTests/Core/Config/ConfigSchemaDeprecationTest.php
   @@ -0,0 +1,33 @@
   +    // A PHPUnit test requires at least one assertion to be performed.
   +    $this->assertTrue(TRUE);
   

   How about testing the expected config value. It's better than an assertTrue(TRUE).

#25 was taken care of.

We would need to add a change record and update https://www.drupal.org/node/1905070 docs, the later may be done after commit.

Needs something to be added to \Drupal\Core\TypedData\PrimitiveInterface or anywhere else? Or we just rely on d.org documentation?
Is there any kind of validation or could I add whatever key here? I'm already adding this 'deprecated' one even if it's not parsed, for example.

Answering my own question, schema doesn't have a meta-schema, so there's no need to add anything else.

@penyaskito config schema is definitely meta enough :)

It would be good to update some documentation somewhere - the docs in core.api.php feel too much of an overview. The suggested docs for the policy page are good. We definitely need a CR here (needs work for that). Also a small snippet for the release notes (see issue summary).

Thanks! This is a great idea.

This needs a CR too I think, as well as documentation somewhere in the codebase, like in an api.php group or such.

I think this is a bit different to other deprecations because it's adding a new key to a YAML format. It looks to me like we could add this to https://www.drupal.org/docs/drupal-apis/configuration-api/configuration-...

@claudiu.cristea sorry good point, that's a docs page and not api.drupal.org...

It might be worth a follow-up issue to move that documentation to an api.php somewhere, but yes we can't do that here.

Committed 0fb041f and pushed to 9.1.x. Thanks!

Filed follow-up for config inspector #3168268: Display deprecated schema usage

Published https://www.drupal.org/node/3129881.

Well done everyone!

Created the followup asked for in #38, #3311747: Document configuration schema api key in an api.php.