Clarify how to include devtools using Maven

Closes spring-projectsgh-48641

Author: snicoll

build-plugin/spring-boot-maven-plugin/src/docs/antora/modules/maven-plugin/pages/build-image.adoc

@@ -23,6 +23,8 @@ In the rest of this section, `build-image` is used to refer to either the `build
 TIP: While the buildpack runs from an xref:packaging.adoc[executable archive], it is not necessary to execute the `repackage` goal first as the executable archive is created automatically if necessary.
 When the `build-image` repackages the application, it applies the same settings as the `repackage` goal would, that is dependencies can be excluded using one of the exclude options.
 The `spring-boot-devtools` and `spring-boot-docker-compose` modules are automatically excluded by default (you can control this using the `excludeDevtools` and `excludeDockerCompose` properties).
+Pay also attention that optional dependencies are not included by default.
+If you have defined those modules as optional, you also need to set the `includeOptional` property to `true`.
 
 
 

build-plugin/spring-boot-maven-plugin/src/docs/antora/modules/maven-plugin/pages/packaging.adoc

@@ -25,6 +25,8 @@ NOTE: The `outputFileNameMapping` feature of the `maven-war-plugin` is currently
 
 The `spring-boot-devtools` and `spring-boot-docker-compose` modules are automatically excluded by default (you can control this using the `excludeDevtools` and `excludeDockerCompose` properties).
 In order to make that work with `war` packaging, the `spring-boot-devtools` and `spring-boot-docker-compose` dependencies must be set as `optional` or with the `provided` scope.
+Pay also attention that optional dependencies are not included by default.
+If you have defined those modules as optional, you also need to set the `includeOptional` property to `true`.
 
 The plugin rewrites your manifest, and in particular it manages the `Main-Class` and `Start-Class` entries.
 If the defaults don't work you have to configure the values in the Spring Boot plugin, not in the jar plugin.

documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/using/devtools.adoc

@@ -39,7 +39,8 @@ TIP: Flagging the dependency as optional in Maven or using the `developmentOnly`
 
 TIP: Repackaged archives do not contain devtools by default.
 If you want to use a xref:using/devtools.adoc#using.devtools.remote-applications[certain remote devtools feature], you need to include it.
-When using the Maven plugin, set the `excludeDevtools` property to `false`.
+When using the Maven plugin, opt-in for optional dependencies by setting the `includeOptional` property to `true`.
+You also need to set the `excludeDevtools` property to `false`.
 When using the Gradle plugin, xref:gradle-plugin:packaging.adoc#packaging-executable.configuring.including-development-only-dependencies[configure the task's classpath to include the `developmentOnly` configuration].
 
 
@@ -376,13 +377,16 @@ To enable it, you need to make sure that `devtools` is included in the repackage
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-maven-plugin</artifactId>
 			<configuration>
+				<includeOptional>true</includeOptional>
 				<excludeDevtools>false</excludeDevtools>
 			</configuration>
 		</plugin>
 	</plugins>
 </build>
 ----
 
+NOTE: Optional dependencies are not included by default, which explains why `includeOptional` is also present.
+
 Then you need to set the configprop:spring.devtools.remote.secret[] property.
 Like any important password or secret, the value should be unique and strong such that it cannot be guessed or brute-forced.