michael-o commented on a change in pull request #631:
URL: https://github.com/apache/maven/pull/631#discussion_r762958490
##########
File path: maven-caching-extension/src/site/markdown/CACHE-REMOTE.md
##########
@@ -17,23 +17,42 @@
# Overview
-This document describes generic approach to cache setup. The process require
expertise in Maven equivalent to expertise
-required to author and Maven your project build, it implies good knowledge of
both Maven and the project. Due to Maven
-model limitation the process is manual, but allows you to achieve sufficient
control and transparency over caching
-logic.
+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, please keep in mind basic principles:
+
+* Cache is key based, the key is produced by HashTree-like technique. The key
is produced by hashing every configured
+ source code file, every dependency and effective pom (including plugin
parameters) should match into a single key.
+* There is no built-in normalization of line endings in this implementation,
file checksums calculation is raw bytes
+ based. The most obvious implication could be illustrated by a simple Git
checkout. By default, git will check out
+ source code with CRLF line endings on win and LF on Linux. Because of that
builds over same commit on a Linux agent
+ and local build on Windows workstation will yield different checksums.
+* Parameters of plugins are reconciled in runtime. For example to avoid of
accidentally reusing builds which never run
+ tests ensure that critical surefire parameters are tracked (`skipTests` and
similar) in config. The same applies for
+ all over plugins.
# Step-By-Step
+## 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
-It is recommended to fork branch for cache setup purposes as you might need to
do changes to project build as long as
-you go.
+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
-In order to share build results you need shared storage. Basically any http
server which supports http PUT/GET/HEAD
-operations will work. In our case it is a Nginx OSS with file system module.
Add the url to config and
-change `remote@enabled` to true:
+In order to share build results cache needs a shared storage. Basically any
http server which supports http PUT/GET/HEAD
Review comment:
This is not true anymore with Wagon
--
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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
