AlexanderAshitkin commented on code in PR #40: URL: https://github.com/apache/maven-build-cache-extension/pull/40#discussion_r1125518288
########## src/site/markdown/getting-started.md: ########## @@ -17,58 +17,66 @@ ## Getting Started -To on-board incremental Maven you need to complete several steps: +To onboard incremental Maven you need to complete several steps: Review Comment: fixed ########## src/site/markdown/index.md: ########## @@ -19,102 +19,110 @@ Build cache is an extension targeted to simplify and make more efficient work with large builds in Maven. -That is achieved by a combination of features: +A combination of features achieves that: -* Incremental builds over the changed project graph part only -* Subtree support in multimodule projects (caches discovered from the larger project) +* Incremental builds works on the modified part of the project graph part only +* Subtree support for multimodule projects to work on the part of the codebase in isolation * Version normalization to support project version agnostic caches * Project state restoration (partial) to avoid expensive tasks (code generation and similar) -Large projects usually pose scalability challenges and work with such projects require build tool which scales. Cache -extension addresses that with incremental build execution and ability to efficiently work on sub-parts of a larger +Large projects usually pose scalability challenges, and working with such projects requires a build tool that scales. +The cache +extension addresses that with incremental build execution and the ability to efficiently work on sub-parts of a larger project without building and installing dependencies from the larger project. Though, features implemented in Maven -should give noticeable benefits in medium and small sized projects as well. +should also give noticeable benefits in medium and small-sized projects. ### Cache concepts -The idea of the build cache is to calculate key from module inputs, store outputs in cache and restore them later -transparently to the standard Maven core. In order to calculate the key cache engine analyzes source code, build flow, -plugins and their parameters. This allows to deterministically associate each project state with unique key and restore -up-to-date (not changed) projects from cache and rebuild out-of-date(changed) ones. Restoring artifacts associated with -a particular project state improves build times by avoiding re-building unnecessary modules. Cache does not make any -interventions to actual build execution process and fully delegates build work to Maven core. This ensures that -artifacts produced in presence of cache are equivalent to result produced by a standard Maven build. -To achieve accurate key calculation incremental Maven combines automatic introspection -of [project object model](https://maven.apache.org/pom.html#What_is_the_POM) and allows fine-grained tuning by means of -configuration file and xml attributes. Source code content fingerprinting is digests based which is more reliable over -widely used file timestamps in tools like Make or Apache Ant. Deterministic build state allows reliably cache outputs -even of the build in progress and share them between teams using remote cache. Deterministic inputs calculation allows -distributed and parallel builds running in heterogeneous environments (like cloud of build agents) -could efficiently reuse cached build artifacts. Therefore, incremental Maven is particularly well-suited for large Maven -projects that have significant number of small modules. Remote cache in conjunction with relocatable inputs -identification effectively enables "change once - build once" approach across all environments. +The idea of the build cache is to calculate a key from module inputs, store outputs in the cache, and restore them later +transparently to the standard Maven core. The cache deterministically associates each project state with a unique key +and restores it in subsequent builds. It analyzes source code, project model, +plugins, and their parameters. Projects with the same key are up-to-date (not changed) and could be safely restored from +the cache. Projects producing different keys are out-of-date (changed), and the cache fully rebuilds them. In the latter +case, the cache does not make any +interventions to the build execution logic and delegates build work to the standard maven Maven core. This approach +ensures that +artifacts produced in the presence of a cache are equivalent to the result produced by a standard Maven build. +To achieve an accurate key calculation, incremental Maven combines automatic introspection Review Comment: fixed -- 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-unsubscr...@maven.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
