This is an automated email from the ASF dual-hosted git repository.
hboutemy pushed a commit to branch MNG-7129-maven-caching
in repository https://gitbox.apache.org/repos/asf/maven.git
The following commit(s) were added to refs/heads/MNG-7129-maven-caching by this
push:
new 4362220 reworkd documentation links and title levels
4362220 is described below
commit 436222097ce7c17b29091f0fe00df6fdeafef00d
Author: Hervé Boutemy <[email protected]>
AuthorDate: Sun Dec 12 14:55:13 2021 +0100
reworkd documentation links and title levels
---
deploySite.sh | 2 +-
src/site/apt/index.apt | 2 +-
src/site/markdown/cache.md | 12 ++++-----
src/site/markdown/getting-started.md | 4 +--
src/site/markdown/how-to.md | 2 +-
src/site/markdown/parameters.md | 6 ++---
src/site/markdown/performance.md | 16 +++++-------
src/site/markdown/remote-cache.md | 30 +++++++++++-----------
.../{markdown => resources}/maven-cache-config.xml | 0
src/site/site.xml | 22 +++++++++++-----
10 files changed, 52 insertions(+), 44 deletions(-)
diff --git a/deploySite.sh b/deploySite.sh
index d7a5c5f..4a5ba75 100644
--- a/deploySite.sh
+++ b/deploySite.sh
@@ -19,5 +19,5 @@
# under the License.
#
-mvn -Preporting site site:stage "$@"
+mvn -Preporting site site:stage -Danimal.sniffer.skip "$@"
mvn scm-publish:publish-scm "$@"
diff --git a/src/site/apt/index.apt b/src/site/apt/index.apt
index db29a8d..b2ebdf7 100644
--- a/src/site/apt/index.apt
+++ b/src/site/apt/index.apt
@@ -27,4 +27,4 @@ Maven Caching
Maven Incremental Build and Cache (local and remote).
- Read {{{./CACHE.html} more documentation}}.
+ Read {{{./cache.html} more documentation}}.
diff --git a/src/site/markdown/cache.md b/src/site/markdown/cache.md
index 46c3f69..16a23e1 100644
--- a/src/site/markdown/cache.md
+++ b/src/site/markdown/cache.md
@@ -117,12 +117,12 @@ Such scheme allows to validate cache correctness by
reconciling outcomes of cach
## See also
-* [Getting started](getting-started.md) - getting starting with cache and
usage manual
-* [Usage](usage.md) - shared cache setup procedure
-* [Remote cache setup](remote-cache.md) - shared cache setup procedure
-* [How-To](how-to.md) - cookbook for typical scenarios
-* [Performance](performance.md) - performance tuning
-* [Cache Parameters](parameters.md) - description of supported parameters
+* [Getting started](getting-started.html) - getting starting with cache and
usage manual
+* [Usage](usage.html) - shared cache setup procedure
+* [Remote cache setup](remote-cache.html) - shared cache setup procedure
+* [How-To](how-to.html) - cookbook for typical scenarios
+* [Performance](performance.html) - performance tuning
+* [Cache Parameters](parameters.html) - description of supported parameters
* [Sample config file](maven-cache-config.xml)
diff --git a/src/site/markdown/getting-started.md
b/src/site/markdown/getting-started.md
index 56fd82f..d395b0f 100644
--- a/src/site/markdown/getting-started.md
+++ b/src/site/markdown/getting-started.md
@@ -28,8 +28,8 @@ To on-board incremental Maven you need to complete several
steps:
```xml
<extension>
- <groupId>org.apache.maven.caching</groupId>
- <artifactId>maven-caching-extension</artifactId>
+ <groupId>org.apache.maven.extensions</groupId>
+ <artifactId>maven-build-cache-extension</artifactId>
<version>1.0.0-SNAPSHOT</version>
</extension>
```
diff --git a/src/site/markdown/how-to.md b/src/site/markdown/how-to.md
index 3394ef1..56b4832 100644
--- a/src/site/markdown/how-to.md
+++ b/src/site/markdown/how-to.md
@@ -15,7 +15,7 @@
limitations under the License.
-->
-### Overview
+## Overview
Cache configuration provides you additional control over incremental Maven
behavior. Follow it step by step to
understand how it works and figure out your optimal config
diff --git a/src/site/markdown/parameters.md b/src/site/markdown/parameters.md
index 476c046..8f3e3f7 100644
--- a/src/site/markdown/parameters.md
+++ b/src/site/markdown/parameters.md
@@ -15,11 +15,11 @@
limitations under the License.
-->
-# Overview
+## Build Cache Parameters
This documents contains various configuration parameters supported by cache
engine
-## Command line flags
+### Command line flags
| Parameter | Description | Usage Scenario |
| ----------- | ----------- | ----------- |
@@ -32,7 +32,7 @@ This documents contains various configuration parameters
supported by cache engi
| `-Dremote.cache.lazyRestore=(true/false)` | Restore artifacts
from remote cache lazily | Performance optimization |
| `-Dremote.cache.restoreGeneratedSources=(true/false)` | Do not restore
generated sources and directly attached files | Performance optimization |
-## Project level properties
+### Project level properties
Project level parameters allow overriding global parameters on project level
Must be specified as project properties:
diff --git a/src/site/markdown/performance.md b/src/site/markdown/performance.md
index 03a8173..22b409d 100644
--- a/src/site/markdown/performance.md
+++ b/src/site/markdown/performance.md
@@ -15,18 +15,18 @@
limitations under the License.
-->
-# Performance Tuning
+## Performance Tuning
Various setup options which affect cache performance.
-## General notes
+### General notes
Tuning of cache performance could reduce both resources consumption and build
execution time but that is not guaranteed.
In many scenarios build time of invalidated (changed) projects could be
dominating in overall build time. Performance
wins achieved by a faster cache engine might not correlate with final build
times in straightforward way. As usual with
performance, effect of performance optimizations should be carefully measured
in relevant scenarios.
-## Hash algorithm selection
+### Hash algorithm selection
By default, cache uses SHA-256 algorithm which is sufficiently fast and
provides negligible probability of hash
collisions. In projects with large codebase, performance of hash algorithms
becomes more important and in such
@@ -43,7 +43,7 @@ or
<hashAlgorithm>XXMM</hashAlgorithm>
```
-## Filter out unnecessary/huge artifacts
+### Filter out unnecessary/huge artifacts
Price of uploading and downloading from cache of huge artifacts could be
significant. In many scenarios assembling WAR,
EAR or ZIP archive could be done more efficiently locally from cached JARs
than storing bundles. In order to filter out
@@ -59,7 +59,7 @@ artifacts add configuration section:
</cache>
```
-## Use lazy restore
+### Use lazy restore
By default, cache tries to restore all artifacts for a project preemptively.
Lazy restore could give a significant time
and resources wins for remote cache by avoiding requesting and downloading
unnecessary artifacts from cache. Use command
@@ -72,7 +72,7 @@ line flag:
Note: In case of cache corruption lazy cache cannot fallback to normal
execution, it will fail instead. To heal the
corrupted cache need to force rewrite of the cache or remove corrupted cache
entries manually
-## Disable project files restoration
+### Disable project files restoration
By default, cache support partial restore of source code state from cached
generated sources (and potentially more,
depending on configuration). This could be helpful in local environment, but
likely unnecessary and adds overhead in
@@ -82,7 +82,7 @@ continuous integration. To disable add command line flag
-Dremote.cache.restoreGeneratedSources=false";
```
-## Disable post-processing of archives(JARs, WARs, etc) META-INF
+### Disable post-processing of archives(JARs, WARs, etc) META-INF
Post-processing is disabled by default, but for some projects cache could be
configured to auto-correct metadata (most
notably [MANIFEST.MF
`Implementation-Version`](https://docs.oracle.com/javase/8/docs/technotes/guides/jar/jar.html#Main_Attributes))
@@ -99,5 +99,3 @@ for the build (continuous integration, `verify` scenarios and
similar) consider
...
</cache>
```
-
-
diff --git a/src/site/markdown/remote-cache.md
b/src/site/markdown/remote-cache.md
index 74b0bdc..39bf151 100644
--- a/src/site/markdown/remote-cache.md
+++ b/src/site/markdown/remote-cache.md
@@ -15,13 +15,13 @@
limitations under the License.
-->
-# Overview
+## Overview
This document describes generic approach to remote cache setup. The process
implies good knowledge of both Maven and the
project. Due to Maven model limitation the process is semi-manual, but allows
you to achieve sufficient control and
transparency over caching logic.
-## Before you start
+### Before you start
Before you start, please keep in mind basic principles:
@@ -36,21 +36,21 @@ Before you start, please keep in mind basic principles:
tests ensure that critical surefire parameters are tracked (`skipTests` and
similar) in config. The same applies for
all over plugins.
-# Step-By-Step
+## Step-By-Step
-## Minimize number of moving parts
+### Minimize number of moving parts
* Run build with single threaded builder to make sure logs from different
modules do not interfere
* Use the same branch which no-one else commits to
* Designate single agent/node for CI builds
* Preferably use the same OS between CI and local machine
-## Fork branch for cache setup purposes
+### Fork branch for cache setup purposes
Fork stable code branch for cache setup purposes as you will need source code
which doesn't change over time of setup.
Also, you likely will need to do code changes as long as you go.
-## Setup http server to store artifacts
+### Setup http server to store artifacts
In order to share build results cache needs a shared storage. The simplest
option is to set up a http server which
supports http PUT/GET/HEAD operations will suffice (Nginx, Apache or similar).
Add the url to config and
@@ -73,13 +73,13 @@ Beside the http server, remote cache could be configured
using any storage which
by [Maven Wagon](https://maven.apache.org/wagon/). That includes a wide set of
options, including SSH, FTP and many
others. See Wagon documentation for a full list of options and other details.
-## Build selection
+### Build selection
Build stored in cache ideally should be a build assembled in the most correct,
comprehensive and complete way. Pull
requests builds are good candidates to populate cache usually because this is
there quality safeguards are applied
normally.
-## CI Build setup to seed shared cache
+### CI Build setup to seed shared cache
Allow writes in remote cache add jvm property to designated CI builds.
@@ -90,7 +90,7 @@ Allow writes in remote cache add jvm property to designated
CI builds.
Run the build, review log and ensure that artifacts are uploaded to remote
cache. Now, rerun build and ensure that it
completes almost instantly because it is fully cached.
-## Remote cache relocation to local builds
+### Remote cache relocation to local builds
As practice shows, developers often don't realize that builds they run in
local and CI environments are different. So
straightforward attempt to reuse remote cache in local build usually results
in cache misses because of difference in
@@ -127,15 +127,15 @@ Review `buildsdiff.xml` file and eliminate detected
discrepancies. You can also
low level insights. See techniques to configure cache in [How-To](how-to.md)
and troubleshooting of typical issues
in the section below.
-# Common issues
+## Common issues
-## Issue 1: Local checkout is with different line endings
+### Issue 1: Local checkout is with different line endings
Solution: normalise line endings. Current implementation doesn't have built-in
line endings normalization, it has to be
done externally. In git it is recommended to use `.gitattributes` file to
establish consistent line endings across all
envs for file types specific to this project
-## Issue 2: Effective poms mismatch because of plugins injection by profiles
+### Issue 2: Effective poms mismatch because of plugins injection by profiles
Different profiles between remote and local builds likely result in different
text of effective poms. As effective pom
contributes hash value to the key that could lead to cache misses. Solution:
instead of adding/removing specific plugins
@@ -191,7 +191,7 @@ Use:
Hint: effective poms could be found in `buildinfo` files under
`/build/projectsInputInfo/item[@type='pom']`
xpath (`item type="pom"`).
-## Issue 3: Effective pom mismatch because of environment specific properties
+### Issue 3: Effective pom mismatch because of environment specific properties
Potential reason: Sometimes it is not possible to avoid discrepancies in
different environments - for example if plugin
takes command line as parameter, it will be likely different on Win and linux.
Such commands will appear in effective
@@ -211,7 +211,7 @@ filter out such properties from effective pom:
</input>
```
-## Issue 4: Unexpected or transient files in cache key calculation
+### Issue 4: Unexpected or transient files in cache key calculation
Potential reasons: plugins or tests emit temporary files (logs and similar) in
non-standard locations. Solution: adjust
global exclusions list to filter out the unexpected files:
@@ -224,7 +224,7 @@ global exclusions list to filter out the unexpected files:
see sample config for exact syntax
-## Issue 5: Difference in tracked plugin properties
+### Issue 5: Difference in tracked plugin properties
Tracked property in config means it is critical for determining is build up to
date or not. Discrepancies could happen
for any plugin for a number of reasons. Example: local build is using java
target 1.6, remote: 1.8. `buildsdiff.xml`
diff --git a/src/site/markdown/maven-cache-config.xml
b/src/site/resources/maven-cache-config.xml
similarity index 100%
rename from src/site/markdown/maven-cache-config.xml
rename to src/site/resources/maven-cache-config.xml
diff --git a/src/site/site.xml b/src/site/site.xml
index aa24fb5..15f4f67 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -25,26 +25,36 @@ under the License.
<edit>${project.scm.url}</edit>
<body>
+ <breadcrumbs>
+ <item name="Ref" href="../" />
+ <item name="Maven Build Cache Extension" href="./" />
+ </breadcrumbs>
+
<menu name="Overview">
<item name="Introduction" href="index.html"/>
<item name="JavaDocs" href="apidocs/index.html"/>
<item name="Source Xref" href="xref/index.html"/>
<!--item name="FAQ" href="faq.html"/-->
- <item name="maven-cache-config.xml" href="cache-config.html"/>
</menu>
<menu name="Documentation">
- <item name="Overview" href="CACHE.html"/>
- <item name="Howto" href="CACHE-HOWTO.html"/>
- <item name="Parameters" href="CACHE-PARAMETERS.html"/>
- <item name="Remote" href="CACHE-REMOTE.html"/>
+ <item name="Overview" href="cache.html"/>
+ <item name="Getting Started" href="getting-started.html"/>
+ <item name="Usage" href="usage.html"/>
+ <item name="Remote Cache Setup" href="remote-cache.html"/>
+ <item name="Howto" href="how-to.html"/>
+ <item name="Performance" href="performance.html"/>
+ <item name="Cache Parameters" href="parameters.html"/>
+ </menu>
+
+ <menu name="Reference">
+ <item name="maven-cache-config.xml" href="cache-config.html"/>
</menu>
<menu name="Cache Internals">
<item name="buildinfo.xml" href="cache-build.html"/>
<item name="diff-*.xml" href="cache-diff.html"/>
<item name="cache-report.xml" href="cache-report.html"/>
- <!--item name="FAQ" href="faq.html"/-->
</menu>
<menu ref="parent"/>
