Change setting's deprecation message wording (#120718) (#124340)

Depending on whether a message is critical or warning a message should
indicate to check breaking changes documentation (critical level) or
deprecation changes documentation (warn level)

relates #79666

Author: alexey-ivanov-es

modules/repository-s3/src/test/java/org/elasticsearch/repositories/s3/RepositoryCredentialsTests.java

@@ -107,8 +107,10 @@ public void testRepositoryCredentialsOverrideSecureCredentials() {
         assertThat(credentials.getAWSSecretKey(), is("insecure_aws_secret"));
 
         assertCriticalWarnings(
-            "[access_key] setting was deprecated in Elasticsearch and will be removed in a future release.",
-            "[secret_key] setting was deprecated in Elasticsearch and will be removed in a future release.",
+            "[access_key] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the breaking changes documentation for the next major version.",
+            "[secret_key] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the breaking changes documentation for the next major version.",
             S3Repository.INSECURE_CREDENTIALS_DEPRECATION_WARNING
         );
     }
@@ -193,8 +195,10 @@ public void testReinitSecureCredentials() {
 
         if (hasInsecureSettings) {
             assertCriticalWarnings(
-                "[access_key] setting was deprecated in Elasticsearch and will be removed in a future release.",
-                "[secret_key] setting was deprecated in Elasticsearch and will be removed in a future release.",
+                "[access_key] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                    + "See the breaking changes documentation for the next major version.",
+                "[secret_key] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                    + "See the breaking changes documentation for the next major version.",
                 S3Repository.INSECURE_CREDENTIALS_DEPRECATION_WARNING
             );
         }

server/src/main/java/org/elasticsearch/common/settings/Setting.java

@@ -25,7 +25,6 @@
 import org.elasticsearch.core.TimeValue;
 import org.elasticsearch.core.Tuple;
 import org.elasticsearch.core.UpdateForV10;
-import org.elasticsearch.core.UpdateForV9;
 import org.elasticsearch.index.mapper.DateFieldMapper;
 import org.elasticsearch.xcontent.ToXContentObject;
 import org.elasticsearch.xcontent.XContentBuilder;
@@ -83,6 +82,11 @@
  * </pre>
  */
 public class Setting<T> implements ToXContentObject {
+    private static final String DEPRECATED_MESSAGE_TEMPLATE =
+        "[{}] setting was deprecated in Elasticsearch and will be removed in a future release. "
+            + "See the %s documentation for the next major version.";
+    private static final String DEPRECATED_WARN_MESSAGE = Strings.format(DEPRECATED_MESSAGE_TEMPLATE, "deprecation");
+    private static final String DEPRECATED_CRITICAL_MESSAGE = Strings.format(DEPRECATED_MESSAGE_TEMPLATE, "breaking changes");
 
     public enum Property {
         /**
@@ -651,10 +655,8 @@ void checkDeprecation(Settings settings) {
         if (this.isDeprecated() && this.exists(settings)) {
             // It would be convenient to show its replacement key, but replacement is often not so simple
             final String key = getKey();
-            @UpdateForV9(owner = UpdateForV9.Owner.CORE_INFRA) // https://github.com/elastic/elasticsearch/issues/79666
-            String message = "[{}] setting was deprecated in Elasticsearch and will be removed in a future release.";
             if (this.isDeprecatedWarningOnly()) {
-                Settings.DeprecationLoggerHolder.deprecationLogger.warn(DeprecationCategory.SETTINGS, key, message, key);
+                Settings.DeprecationLoggerHolder.deprecationLogger.warn(DeprecationCategory.SETTINGS, key, DEPRECATED_WARN_MESSAGE, key);
             } else if (this.isDeprecatedAndRemoved()) {
                 Settings.DeprecationLoggerHolder.deprecationLogger.critical(
                     DeprecationCategory.SETTINGS,
@@ -663,7 +665,12 @@ void checkDeprecation(Settings settings) {
                     key
                 );
             } else {
-                Settings.DeprecationLoggerHolder.deprecationLogger.critical(DeprecationCategory.SETTINGS, key, message, key);
+                Settings.DeprecationLoggerHolder.deprecationLogger.critical(
+                    DeprecationCategory.SETTINGS,
+                    key,
+                    DEPRECATED_CRITICAL_MESSAGE,
+                    key
+                );
             }
         }
     }

server/src/test/java/org/elasticsearch/cluster/ClusterModuleTests.java

@@ -189,7 +189,8 @@ public void testRegisterShardsAllocator() {
         ClusterModule module = newClusterModuleWithShardsAllocator(settings, "custom", FakeShardsAllocator::new);
         assertEquals(FakeShardsAllocator.class, module.shardsAllocator.getClass());
         assertCriticalWarnings(
-            "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release."
+            "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the breaking changes documentation for the next major version."
         );
     }
 
@@ -219,15 +220,17 @@ public void testUnknownShardsAllocator() {
         );
         assertEquals("Unknown ShardsAllocator [dne]", e.getMessage());
         assertCriticalWarnings(
-            "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release."
+            "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the breaking changes documentation for the next major version."
         );
     }
 
     public void testShardsAllocatorFactoryNull() {
         Settings settings = Settings.builder().put(ClusterModule.SHARDS_ALLOCATOR_TYPE_SETTING.getKey(), "bad").build();
         expectThrows(NullPointerException.class, () -> newClusterModuleWithShardsAllocator(settings, "bad", () -> null));
         assertCriticalWarnings(
-            "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release."
+            "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the breaking changes documentation for the next major version."
         );
     }
 

server/src/test/java/org/elasticsearch/cluster/routing/allocation/ClusterRebalanceRoutingTests.java

@@ -704,7 +704,8 @@ public void beforeAllocation(RoutingAllocation allocation) {
             }
         );
         assertCriticalWarnings(
-            "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release."
+            "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the breaking changes documentation for the next major version."
         );
 
         Metadata metadata = Metadata.builder()

server/src/test/java/org/elasticsearch/cluster/routing/allocation/IndexBalanceTests.java

@@ -449,7 +449,8 @@ public void testRebalanceShouldNotPerformUnnecessaryMovesWithMultipleConcurrentR
 
         final var allocationService = createAllocationService(settings);
         assertCriticalWarnings(
-            "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release."
+            "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the breaking changes documentation for the next major version."
         );
 
         assertTrue(

server/src/test/java/org/elasticsearch/cluster/routing/allocation/ThrottlingAllocationTests.java

@@ -200,7 +200,8 @@ public void testThrottleIncomingAndOutgoing() {
             snapshotsInfoService
         );
         assertCriticalWarnings(
-            "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release."
+            "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the breaking changes documentation for the next major version."
         );
         logger.info("Building initial routing table");
 

server/src/test/java/org/elasticsearch/index/codec/PerFieldMapperCodecTests.java

@@ -112,7 +112,8 @@ public void testUseBloomFilterWithTimestampFieldEnabled_disableBloomFilter() thr
         assertThat(perFieldMapperCodec.useBloomFilter("_id"), is(false));
         assertThat(perFieldMapperCodec.getPostingsFormatForField("_id"), instanceOf(ES812PostingsFormat.class));
         assertWarnings(
-            "[index.bloom_filter_for_id_field.enabled] setting was deprecated in Elasticsearch and will be removed in a future release."
+            "[index.bloom_filter_for_id_field.enabled] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the deprecation documentation for the next major version."
         );
     }
 

server/src/test/java/org/elasticsearch/snapshots/InternalSnapshotsInfoServiceTests.java

@@ -362,7 +362,8 @@ public IndexShardSnapshotStatus.Copy getShardSnapshotStatus(SnapshotId snapshotI
                 snapshotsInfoService
             );
             assertCriticalWarnings(
-                "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release."
+                "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                    + "See the breaking changes documentation for the next major version."
             );
             applyClusterState(
                 "starting shards for " + indexName,

server/src/test/java/org/elasticsearch/snapshots/SnapshotResiliencyTests.java

@@ -2202,7 +2202,8 @@ public RecyclerBytesStreamOutput newNetworkBytesStream() {
                     snapshotsInfoService
                 );
                 assertCriticalWarnings(
-                    "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release."
+                    "[cluster.routing.allocation.type] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                        + "See the breaking changes documentation for the next major version."
                 );
                 rerouteService = new BatchedRerouteService(clusterService, allocationService::reroute);
                 rerouteServiceSetOnce.set(rerouteService);

server/src/test/java/org/elasticsearch/transport/TransportServiceLifecycleTests.java

@@ -171,7 +171,8 @@ public void testInternalSendExceptionForksToGenericIfHandlerDoesNotForkAndStackO
             assertEquals("simulated exception in sendRequest", getSendRequestException(future, IOException.class).getMessage());
         }
         assertWarnings(
-            "[transport.enable_stack_protection] setting was deprecated in Elasticsearch and will be removed in a future release."
+            "[transport.enable_stack_protection] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the breaking changes documentation for the next major version."
         );
     }
 
@@ -264,7 +265,8 @@ public void testOnConnectionClosedUsesHandlerExecutor() {
         onConnectionClosedUsesHandlerExecutor(settings, executorName, expectedExecutor);
         if (withSetting) {
             assertWarnings(
-                "[transport.enable_stack_protection] setting was deprecated in Elasticsearch and will be removed in a future release."
+                "[transport.enable_stack_protection] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                    + "See the breaking changes documentation for the next major version."
             );
         }
     }
@@ -276,7 +278,8 @@ public void testOnConnectionCloseStackOverflowAvoidance() {
             ThreadPool.Names.GENERIC
         );
         assertWarnings(
-            "[transport.enable_stack_protection] setting was deprecated in Elasticsearch and will be removed in a future release."
+            "[transport.enable_stack_protection] setting was deprecated in Elasticsearch and will be removed in a future release. "
+                + "See the breaking changes documentation for the next major version."
         );
     }