Documentation updates (apache#28)

* Documentation updates - fixed references to config file after rename, added notes about subtree discovery * Documentation updates - reworded subtree build section Co-authored-by: aashitki <alex.ashitkin@db.com> Co-authored-by: Guillaume Nodet <gnodet@gmail.com>

Author: 3 people

src/site/markdown/getting-started.md

@@ -20,7 +20,7 @@
 To on-board incremental Maven you need to complete several steps:
 
 * Declare caching extension in your project (either in `pom.xml` or `.mvn/extensions.xml`)
-* Add `maven-cache-config.xml` cache config in `.mvn/` (optional) to customize default behavior
+* Add `maven-build-cache-config.xml` cache config in `.mvn/` (optional) to customize default behavior
 * Validate build results and iteratively, adjust config to properly reflect project specifics
 * Setup remote cache (optional)
 
@@ -38,27 +38,30 @@ either in `pom.xml`'s `<project>/<build>/<extensions>` or in `.mvn/extensions.xm
 
 ### Adding build cache config
 
-Copy [default config `maven-build-cache-config.xml`](../resources/maven-build-cache-config.xml)
+Copy template config [`maven-build-cache-config.xml`](../resources/maven-build-cache-config.xml)
 to [`.mvn/`](https://maven.apache.org/configure.html) directory of your project. 
 To get overall understanding of build cache machinery, it is recommended to review the config and read comments. In typical
-scenario you need to adjust:
+scenario you need to:
 
-* Exclusions for unstable, temporary files or environment specific files
-* Plugins reconciliation rules – add critical plugins parameters to reconciliation
-* Source code files selectors. Though source code locations discovered automatically from project and plugins config,
+* Exclude unstable, temporary files or environment specific files
+* Add plugins reconciliation rules – add critical plugins parameters to reconciliation
+* Configure precise source code files selectors. Though source code locations discovered automatically from project and plugins config,
  there might be edge cases.
-* remote cache location (if remote cache is used)
+* Add remote cache location (if remote cache is used)
 
 ### Adjusting build cache config
 
 Having extension run usual command, like `mvn package`. Verify the caching engine is activated:
 
-* Check log output - there should be cache related output or initialization error message.
+* Check log output - there should be cache related output or initialization error message:
+ ```
+ [INFO] Loading cache configuration from <project dir>/.mvn/maven-build-cache-config.xml
+ ```
 * Navigate to your local repo directory - there should be a sibling directory `cache` next to the usual
  local `repository`.
 * Find `buildinfo.xml` in the cache repository for typical module and review it. Ensure that
  * expected source code files are present in the build info
- * all critical plugins and their critical parameters are covered by config
+ * Review all plugings used in the build and add their critical parameters to reconciliation
 
 It is recommended to find the best working trade-off between fairness and cache efficiency. Adding unnecessary rules and
 checks could reduce both performance and cache efficiency (hit rate).

src/site/markdown/how-to.md

@@ -26,8 +26,8 @@ Absolutely minimal config
 
 ```xml
 <?xml version="1.0" encoding="UTF-8" ?>
-<cache xmlns="http://maven.apache.org/CACHE-CONFIG/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/CACHE-CONFIG/1.0.0 http://maven.apache.org/xsd/cache-config-1.0.0.xsd">
+<cache xmlns="http://maven.apache.org/BUILD-CACHE-CONFIG/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/BUILD-CACHE-CONFIG/1.0.0 http://maven.apache.org/xsd/cache-config-1.0.0.xsd">
 
  <configuration>
  <enabled>true</enabled>

src/site/markdown/usage.md

@@ -24,11 +24,23 @@ Once extension is activated, cache will kick-in automatically on every lifecycle
 Build could be invoked on any module in project and will try to discover cache by introspecting dependencies. In order
 to identify which dependencies are part of cacheable project the cache engine needs to know:
 
-* full project root location which must be passed with `-Dmaven.multiModuleProjectDirectory`
-* Specify profiles which activate full graph in config:
+* Full project root location which must be passed with `-Dmaven.multiModuleProjectDirectory`
+* Profiles which activate full graph in project build. Underlying implementation logic is to introspect reactor
+ graph in `full` mode to discover which dependencies are part of the full project and cacheable. This information will
+ be used when subtree is being build to identify dependencies as a part of a wider project and process them from cache:
 
-```
-TBD
+```xml
+<configuration>
+ ...
+ <multiModule>
+ <discovery>
+ <scanProfiles>
+ <scanProfile>my-full-project-profile</scanProfile>
+ </scanProfiles>
+ </discovery>
+ </multiModule>
+ ...
+</configuration>
 ```
 
 ## Disable cache

src/site/resources/maven-build-cache-config.xml

@@ -15,8 +15,8 @@
  See the License for the specific language governing permissions and
  limitations under the License.
 -->
-<cache xmlns="http://maven.apache.org/CACHE-CONFIG/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/CACHE-CONFIG/1.0.0 target/generated-resources/modello/build-cache-config-1.0.0.xsd">
+<cache xmlns="http://maven.apache.org/BUILD-CACHE-CONFIG/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache¬.org/BUILD-CACHE-CONFIG/1.0.0 target/generated-resources/modello/build-cache-config-1.0.0.xsd">
 
  <!--
  Template Maven build cache configuration