Update documentation about using GraalVM configuration files

Starting with Mandrel 23.1 and GraalVM for JDK 21 the use of
`-H:ResourceConfigurationFiles` and `-H:ReflectionConfigurationFiles` is
marked as experimental and requires the use of
`-H::±UnlockExperimentalVMOptions` to avoid warnings (see
oracle/graal#7190), while in the future (planned for the next release)
the presence of this option will be mandatory when using experimental
options (see oracle/graal#7370).

Furthermore, as described in oracle/graal#7487 Mandrel and GraalVM will also adopt glob patterns in the future (planned for the next release) and gradually phase out the ability to use exclude patterns.

The aim of this change is to inform Quarkus users that they are
responsible for keeping such configuration files up to date and to make
clear that they need to start using the
`-H::±UnlockExperimentalVMOptions` option.

docs/src/main/asciidoc/writing-native-applications-tips.adoc

@@ -37,6 +37,8 @@ So this directory is not a shortcut for "let's automatically include these resou
 Other resources should be declared explicitly.
 ====
 
+==== Using the `quarkus.native.resources.includes` configuration property
+
 To include more resources in the native executable, the easiest way is to use the `quarkus.native.resources.includes` configuration property,
 and its counterpart to exclude resources `quarkus.native.resources.excludes`.
 
@@ -55,8 +57,19 @@ will include:
 * all files in the `foo/` directory and its subdirectories except for files in `foo/private/` and its subdirectories,
 * all text files in the `bar/` directory and its subdirectories.
 
+==== Using a configuration file
+
 If globs are not sufficiently precise for your use case and you need to rely on regular expressions, or if you prefer relying on the GraalVM infrastructure,
-you can also create a `resources-config.json` (the most common location is within `src/main/resources`) JSON file defining which resources should be included:
+you can also create a `resources-config.json` (the most common location is within `src/main/resources`) JSON file defining which resources should be included.
+
+[WARNING]
+====
+Relying on the GraalVM infrastructure means that you are responsible for keeping the configuration file up to date as new Mandrel and GraalVM versions are released.
+
+Please also note that the `resources-config.json` file will be overwritten by Quarkus if placed directly under `src/main/resources/META-INF/native-image/` as Quarkus generates its own configuration file in this directory.
+====
+
+An example of such a file is the following:
 
 [source,json]
 ----
@@ -84,9 +97,18 @@ The final order of business is to make the configuration file known to the `nati
 
 [source,properties]
 ----
-quarkus.native.additional-build-args =-H:ResourceConfigurationFiles=resources-config.json
+quarkus.native.additional-build-args =\
+    -H:+UnlockExperimentalVMOptions,\
+    -H:ResourceConfigurationFiles=resources-config.json,\
+    -H:-UnlockExperimentalVMOptions
 ----
 
+[NOTE]
+====
+Starting with Mandrel 23.1 and GraalVM for JDK 21, `-H:ResourceConfigurationFiles=resources-config.json` results in a warning being shown unless wrapped in `-H:+UnlockExperimentalVMOptions` and `-H:-UnlockExperimentalVMOptions`.
+The absence of these options will result in build failures in the future.
+====
+
 In the previous snippet we were able to simply use `resources-config.json` instead of specifying the entire path of the file simply because it was added to `src/main/resources`.
 If the file had been added to another directory, the proper file path would have had to be specified manually.
 
@@ -97,8 +119,10 @@ Multiple options may be separated by a comma. For example, one could use:
 [source,properties]
 ----
 quarkus.native.additional-build-args =\
+    -H:+UnlockExperimentalVMOptions,\
     -H:ResourceConfigurationFiles=resources-config.json,\
-    -H:ReflectionConfigurationFiles=reflection-config.json
+    -H:ReflectionConfigurationFiles=reflection-config.json,\
+    -H:-UnlockExperimentalVMOptions
 ----
 
 in order to ensure that various resources are included and additional reflection is registered.
@@ -115,7 +139,9 @@ When using Maven, we could use the following configuration:
         <id>native</id>
         <properties>
             <quarkus.package.type>native</quarkus.package.type>
-            <quarkus.native.additional-build-args>-H:ResourceConfigurationFiles=resources-config.json</quarkus.native.additional-build-args>
+            <quarkus.native.additional-build-args>
+                -H:+UnlockExperimentalVMOptions,-H:ResourceConfigurationFiles=resources-config.json,-H:-UnlockExperimentalVMOptions
+            </quarkus.native.additional-build-args>
         </properties>
     </profile>
 </profiles>
@@ -225,7 +251,12 @@ public class MyReflectionConfiguration {
 
 ==== Using a configuration file
 
-You can use a configuration file to register classes for reflection.
+You can also use a configuration file to register classes for reflection, if you prefer relying on the GraalVM infrastructure.
+
+[WARNING]
+====
+Relying on the GraalVM infrastructure means that you are responsible for keeping the configuration file up to date as new Mandrel and GraalVM versions are released.
+====
 
 As an example, in order to register all methods of class `com.acme.MyClass` for reflection, we create `reflection-config.json` (the most common location is within `src/main/resources`)
 
@@ -253,9 +284,18 @@ The final order of business is to make the configuration file known to the `nati
 
 [source,properties]
 ----
-quarkus.native.additional-build-args =-H:ReflectionConfigurationFiles=reflection-config.json
+quarkus.native.additional-build-args =\
+    -H:+UnlockExperimentalVMOptions,\
+    -H:ReflectionConfigurationFiles=reflection-config.json,\
+    -H:-UnlockExperimentalVMOptions
 ----
 
+[NOTE]
+====
+Starting with Mandrel 23.1 and GraalVM for JDK 21, `-H:ResourceConfigurationFiles=resources-config.json` results in a warning being shown unless wrapped in `-H:+UnlockExperimentalVMOptions` and `-H:-UnlockExperimentalVMOptions`.
+The absence of these options will result in build failures in the future.
+====
+
 In the previous snippet we were able to simply use `reflection-config.json` instead of specifying the entire path of the file simply because it was added to `src/main/resources`.
 If the file had been added to another directory, the proper file path would have had to be specified manually.
 
@@ -266,8 +306,10 @@ Multiple options may be separated by a comma. For example, one could use:
 [source,properties]
 ----
 quarkus.native.additional-build-args =\
+    -H:+UnlockExperimentalVMOptions,\
     -H:ResourceConfigurationFiles=resources-config.json,\
-    -H:ReflectionConfigurationFiles=reflection-config.json
+    -H:ReflectionConfigurationFiles=reflection-config.json,\
+    -H:-UnlockExperimentalVMOptions
 ----
 
 in order to ensure that various resources are included and additional reflection is registered.
@@ -284,7 +326,9 @@ When using Maven, we could use the following configuration:
         <id>native</id>
         <properties>
             <quarkus.package.type>native</quarkus.package.type>
-            <quarkus.native.additional-build-args>-H:ReflectionConfigurationFiles=reflection-config.json</quarkus.native.additional-build-args>
+            <quarkus.native.additional-build-args>
+                -H:+UnlockExperimentalVMOptions,-H:ReflectionConfigurationFiles=reflection-config.json,-H:-UnlockExperimentalVMOptions
+            </quarkus.native.additional-build-args>
         </properties>
     </profile>
 </profiles>