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 class MapperService extends AbstractIndexComponent implements Closeable {
     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 @@ public class MapperService extends AbstractIndexComponent implements Closeable {
 
         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() +
+                throw new IllegalArgumentException(DEFAULT_MAPPING_ERROR_MESSAGE);
-                        "]: defaults mappings are not useful anymore now that indices can have at most one type.");
             } 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 " +
+                deprecationLogger.deprecated(DEFAULT_MAPPING_ERROR_MESSAGE);
-                        "cannot have more than one type");
             }
             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 class LegacyMapperServiceTests extends ESSingleNodeTestCase {
         }
         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 class MapperServiceTests extends ESSingleNodeTestCase {
         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"
+        assertEquals(MapperService.DEFAULT_MAPPING_ERROR_MESSAGE, e.getMessage());
-            + " that indices can have at most one type.", e.getMessage());
     }
 
     public void testFieldNameLengthLimit() throws Throwable {