[GitHub] [maven-build-cache-extension] AlexanderAshitkin commented on a diff in pull request #40: Cache documentation improvements

["AlexanderAshitkin (via GitHub)" <gi...@apache.org>]

AlexanderAshitkin commented on code in PR #40:
URL: https://github.com/apache/maven-build-cache-extension/pull/40#discussion_r1186945928


##########
src/site/markdown/getting-started.md.vm:
##########
@@ -18,58 +18,67 @@
 Getting Started
 ---------------
 
-To on-board incremental Maven you need to complete several steps:
+To onboard the build-cache extension you need to complete several steps:
 
 * Declare caching extension in your project (either in `pom.xml` or `.mvn/extensions.xml`)
-* 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
+* Add `maven-build-cache-config.xml` cache config in `.mvn/` (optional) to customize the default behavior
+* Validate build results and iteratively adjust config to reflect project specifics properly
 * Setup remote cache (optional)
 
 #[[###]]# Declaring build cache extension
 
 ```xml
+
 <extension>
     <groupId>org.apache.maven.extensions</groupId>
     <artifactId>maven-build-cache-extension</artifactId>
     <version>${project.version}</version>
 </extension>
 ```
 
-either in `pom.xml`'s `<project>/<build>/<extensions>` or in `.mvn/extensions.xml`'s `<extensions>`
+either in `pom.xml`'s `<project>/<build>/<extensions>` or in `.mvn/extensions.xml`'s `<extensions>`. Using core
+extension model (`.mvn/extensions.xml` file) is preferable as it allows better access to maven APIs and could allow
+more sophisticated optimizations in the future.

Review Comment:
   Assuming that you ask to clarify the statement above, here's the rationale - the core extension initialization model allows binding core API classes, like lifecycle listeners. Besides that, using the cache as a building-level extension tempts the user to initialize the cache in different parts of the project subtree, which was never intended and likely tested. The core extension is the best way to use the cache, which leaves us the door to use all the internal maven APIs future and aligns well with the caching nature. It's just right to make it the recommended option. Honestly, I would deprecate the build extension mode because it doesn't solve any particular problem and just adds accidental complexity.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org