Improve guidance on removing default mappings. (#54915)

In 7.x, an index template will fail to apply if it contains a `_default_`
mapping. Several users have expressed confusion over the fact that loading the
template doesn't show any default mappings. This docs change clarifies that in
order to see all mappings in the template, you must pass `include_type_name`.

docs/reference/migration/migrate_7_0/mappings.asciidoc

@@ -31,6 +31,20 @@ of `_id`.
 The `_default_` mapping has been deprecated in 6.0 and is now no longer allowed
 in 7.0. Trying to configure a `_default_` mapping on 7.x indices will result in
 an error.
+
+If an index template contains a `_default_` mapping, it will fail to create new
+indices. To resolve this issue, the `_default_` mapping should be removed from
+the template. Note that in 7.x, the <<indices-get-template, get template API>>
+does not show the `_default_` mapping by default, even when it is defined in
+the mapping. To see all mappings in the template, the `include_type_name`
+parameter must be supplied:
+
+```
+GET /_template/my_template?include_type_name
+```
+
+For more details on the `include_type_name` parameter and other types-related
+API changes, please see <<removal-of-types>>.
 //end::notable-breaking-changes[]
 
 [float]

server/src/main/java/org/elasticsearch/index/mapper/MapperService.java

@@ -130,6 +130,9 @@ public enum MergeReason {
     private static final ObjectHashSet<String> META_FIELDS = ObjectHashSet.from(SORTED_META_FIELDS);
 
     private static final DeprecationLogger deprecationLogger = new DeprecationLogger(LogManager.getLogger(MapperService.class));
+    static final String DEFAULT_MAPPING_ERROR_MESSAGE = "[_default_] mappings are not allowed on new indices and should no " +
+        "longer be used. See [https://www.elastic.co/guide/en/elasticsearch/reference/current/breaking-changes-7.0.html" +
+        "#default-mapping-not-allowed] for more information.";
 
     private final IndexAnalyzers indexAnalyzers;
 
@@ -449,11 +452,9 @@ private synchronized Map<String, DocumentMapper> internalMerge(@Nullable Documen
 
         if (defaultMapper != null) {
             if (indexSettings.getIndexVersionCreated().onOrAfter(Version.V_7_0_0)) {
-                throw new IllegalArgumentException("The [default] mapping cannot be updated on index [" + index().getName() +
-                        "]: defaults mappings are not useful anymore now that indices can have at most one type.");
+                throw new IllegalArgumentException(DEFAULT_MAPPING_ERROR_MESSAGE);
             } else if (reason == MergeReason.MAPPING_UPDATE) { // only log in case of explicit mapping updates
-                deprecationLogger.deprecated("[_default_] mapping is deprecated since it is not useful anymore now that indexes " +
-                        "cannot have more than one type");
+                deprecationLogger.deprecated(DEFAULT_MAPPING_ERROR_MESSAGE);
             }
             assert defaultMapper.type().equals(DEFAULT_MAPPING);
             results.put(DEFAULT_MAPPING, defaultMapper);

server/src/test/java/org/elasticsearch/index/mapper/LegacyMapperServiceTests.java

@@ -86,7 +86,7 @@ public void testDefaultMappingIsDeprecatedOn6() throws IOException {
         }
         final MapperService mapperService = createIndex("test", settings).mapperService();
         mapperService.merge("_default_", new CompressedXContent(mapping), MapperService.MergeReason.MAPPING_UPDATE);
-        assertWarnings("[_default_] mapping is deprecated since it is not useful anymore now that indexes cannot have more than one type");
+        assertWarnings(MapperService.DEFAULT_MAPPING_ERROR_MESSAGE);
     }
 
 }

server/src/test/java/org/elasticsearch/index/mapper/MapperServiceTests.java

@@ -313,8 +313,7 @@ public void testDefaultMappingIsRejectedOn7() throws IOException {
         MapperService mapperService = createIndex("test").mapperService();
         IllegalArgumentException e = expectThrows(IllegalArgumentException.class,
                 () -> mapperService.merge("_default_", new CompressedXContent(mapping), MergeReason.MAPPING_UPDATE));
-        assertEquals("The [default] mapping cannot be updated on index [test]: defaults mappings are not useful anymore now"
-            + " that indices can have at most one type.", e.getMessage());
+        assertEquals(MapperService.DEFAULT_MAPPING_ERROR_MESSAGE, e.getMessage());
     }
 
     public void testFieldNameLengthLimit() throws Throwable {