Merge branch 'gk/dv-docs-update' into 'main'

Improved the develocity eclipse guide

See merge request !2

readme.md

 # Develocity Service
 
-The Develocity Service at the Eclipse Foundation aims to help Eclipse projects in enabling [Develocity](https://gradle.com/develocity) by providing a seamless integration to CI pipeline. 
+The Develocity Service at the Eclipse Foundation aims to help Eclipse projects in enabling [Develocity](https://gradle.com/develocity) by providing a seamless integration to CI pipeline, as well as local builds (opt-in). 
 
-IMPORTANT: Develocity is currently in an experimental phase (staging). During this period, we will integrate the platform with projects interested in participating. Following this integration phase, we will assess the value of Develocity for the community based on the feedback from these pilot projects, its impact on the foundation's infrastructure, and the effort required to maintain it in operational condition.  
+IMPORTANT: The Eclipse Develocity instance is currently in an experimental phase (staging). During this period, we will integrate the platform with projects interested in participating. Following this integration phase, we will assess the value of Develocity for the community based on the feedback from these pilot projects, its impact on the foundation's infrastructure, and the effort required to maintain it in operational condition.  
 
 At the end of this period, and if the feedback is positive, the platform will move into a production phase. Data from the staging platform will not be migrated.
 
@@ -12,62 +12,150 @@ NOTE: This experimentation is currently focused primarily on Gradle/Maven projec
 
 # What is Develocity?
 
-[Develocity](https://gradle.com/develocity/) is a product developed by [Gradle](https://gradle.com/) as a performance management tool aiming to optimize and accelerate the build and delivery process. 
+[Develocity](https://gradle.com/develocity/) is a product developed by [Gradle](https://gradle.com/) as a build data platform and performance management tool aiming to monitor, debug, optimize and accelerate the build and delivery process.
 
 It provides insights into build times, tests, requests, caches, ... Helping identify inefficiencies/bottlenecks and offers recommendations to improve build speed and reliability. 
 
-Develocity integrates seamlessly with many CI: Jenkins, GitLab CI, GIthub Acions, ...
+Develocity integrates seamlessly with many CI: Jenkins, GitLab CI, Github Acions, ...
 It supports as well many build tools: Gradle, Maven, sbt, bazel
 
+The Eclipse Foundation Develocity instance (available at [https://develocity-staging.eclipse.org/](https://develocity-staging.eclipse.org/)) is fully featured and freely available for use by all Eclipse Foundation projects. When a project onboards its product to Develocity, every CI build and every local build from an authenticated Eclipse committer uploads a Build Scan®. A Build Scan® contains deep build insights that can help troubleshoot build failures and performance issues. By aggregating these Build Scans®, Develocity also provides:
+
+- Dashboards to view all historical Build Scans® and performance trends over time
+- Build failure analytics for enhanced investigation and diagnosis of build failures
+- Test failure analytics to better understand trends and causes around slow, failing, and flaky tests
+
 
 # Quick start!
 
-The Develocity platform can be accessed at [https://develocity-staging.eclipse.org/](https://develocity-staging.eclipse.org/)
+The Develocity platform can be accessed at [https://develocity-staging.eclipse.org/](https://develocity-staging.eclipse.org/) by using your Eclipse account: email / password.
 
-By using your Eclipse account: email/password.
+Generically, onboarding a project to Develocity consists of:
+- Applying Develocity to the build 
+- Configuring Develocity to:
+  - Send Build Scans® to https://develocity-staging.eclipse.org
+  - Always publish Build Scans® if authenticated
+  - Upload Build Scans® in the background for local builds and in the foreground for CI builds
+  - Apply Common Custom User Data to the build
+- Configuring build caching:
+  - Enable local caching for local builds only (unless CI builds are already using local cache)
+  - Disable remote caching (unless builds are already using a remote cache, or you want to use / experiment with it)
 
+## Gradle
+The following sample shows a minimal Develocity configuration for a project building with Gradle 6 or above, using Groovy build scripts. A kotlin script sample (`setting.gradle.kts`) is available [here](https://github.com/gradle/develocity-build-config-samples/blob/main/common-develocity-gradle-configuration-kotlin/settings.gradle.kts).
 
-# CI integration
+#### **`settings.gradle`**
+```groovy
+plugins {
+    id 'com.gradle.develocity' version '3.18.1'
+    id 'com.gradle.common-custom-user-data-gradle-plugin' version '2.0.2'
+}
 
-## Request a CI integration
+def isCI = System.getenv('CI') != null // adjust to your CI provider
 
-A Develocity integration within CI can be requested by filling a ticket on the [helpdesk](https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/issues/new). 
-Please ensure your project lead has approved with a +1 the request. 
+develocity {
+    server = "https://develocity-staging.eclipse.org"
+    projectId = "project-identifier" // adjust to your project identifier / descriptor
+    buildScan {
+        uploadInBackground = !isCI
+        publishing.onlyIf { it.isAuthenticated() }
+        obfuscation {
+            username { _ -> "eclipse-" + System.getenv("EF_SHORT_NAME") + "-bot" }
+            ipAddresses { addresses -> addresses.collect { address -> "0.0.0.0" } }
+        }
+    }
+}
 
-This integration will provide: 
-* A Develocity CI Bot with CI permission on the platform
-* Secrets integration with the Secrets Manager
-* Accessing secrets from any CI
-* Accessing Develocity platform from any CI
+buildCache {
+    // disable local caching in CI, unless already used by the build
+    local {
+        enabled = !isCI
+    }
+    // disable remote caching, unless already used by the build or you want to use / experiment with it
+    remote(develocity.buildCache) {
+        enabled = false
+        push = isCI
+    }
+}
 
-## Build tool integration
+rootProject.name = 'project-name' // adjust to your project name
+```
+See the [Develocity compatibility chart](https://docs.gradle.com/enterprise/compatibility/#develocity_compatibility) for the most recent version of the Develocity Gradle Plugin compatible with the currently installed version of Develocity at [https://develocity-staging.eclipse.org/](https://develocity-staging.eclipse.org/).
 
-1. Gradle
+See the [Common Custom User Data Gradle Plugin releases page](https://github.com/gradle/common-custom-user-data-gradle-plugin/releases) for the most recent version of the Common Custom User Data Gradle Plugin.
 
-Documentation: https://docs.gradle.com/develocity/get-started/
+For information about configuring Develocity for Gradle versions before 6, see the [Develocity Gradle Plugin User Manual](https://docs.gradle.com/enterprise/gradle-plugin/).
 
-create: `settings.gradle.kts`
+## Maven
+The following sample shows a Develocity configuration for a Maven project:
 
-```java
-plugins {
-    id("com.gradle.develocity") version("3.18.1")
-}
+#### **`.mvn/extensions.xml`**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<extensions>
+    <extension>
+        <groupId>com.gradle</groupId>
+        <artifactId>develocity-maven-extension</artifactId>
+        <version>1.22.2</version>
+    </extension>
+    <extension>
+        <groupId>com.gradle</groupId>
+        <artifactId>common-custom-user-data-maven-extension</artifactId>
+        <version>2.0.1</version>
+    </extension>
+</extensions>
+```
 
-develocity {
-    server.set("https://develocity-staging.eclipse.org")
-}
+#### **`.mvn/develocity.xml`**
+```xml
+<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
+<develocity
+    xmlns="https://www.gradle.com/develocity-maven" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="https://www.gradle.com/develocity-maven https://www.gradle.com/schema/develocity-maven.xsd">
+  <server>
+    <url>https://develocity-staging.eclipse.org</url>
+  </server>
+  <projectId>project-identifier</projectId> <!-- adjust to your project identifier / descriptor -->
+  <buildScan>
+    <obfuscation>
+      <username>#{'eclipse-' + env['EF_SHORT_NAME'] + '-bot'}</username>
+      <ipAddresses>0.0.0.0</ipAddresses>
+    </obfuscation>
+    <publishing>
+      <onlyIf>
+        <![CDATA[authenticated]]>
+      </onlyIf>
+    </publishing>
+    <backgroundBuildScanUpload>#{isFalse(env['CI'])}</backgroundBuildScanUpload> <!-- adjust to your CI provider -->
+  </buildScan>
+  <buildCache>
+    <local>
+      <enabled>#{isFalse(env['CI'])}</enabled>
+    </local>
+    <remote>
+      <enabled>false</enabled>
+      <storeEnabled>#{isTrue(env['CI'])}</storeEnabled> <!-- adjust to your CI provider -->
+    </remote>
+  </buildCache>
+</develocity>
 ```
 
-2. Maven
+See the [Develocity compatibility chart](https://docs.gradle.com/enterprise/compatibility/#develocity_compatibility_2) for the most recent version of the Develocity Maven Extension compatible with the currently installed version of Develocity at [https://develocity-staging.eclipse.org/](https://develocity-staging.eclipse.org/).
 
-Documentation: https://docs.gradle.com/develocity/maven-get-started/
+See the [Common Custom User Data Maven Extension releases page](https://github.com/gradle/common-custom-user-data-maven-extension/releases) for the most recent version of the Common Custom User Data Gradle Plugin.
 
-```shell
-mvn com.gradle:develocity-maven-extension:1.22.1:init -Ddevelocity.url=https://develocity-staging.eclipse.org
-```
+# CI integration
 
-This will produce a `.mvn` directory under your project structure with files: `develocity.xml` and `extensions.xml`.
+## Request a CI integration
+
+A Develocity integration within CI can be requested by filling a ticket on the [helpdesk](https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/issues/new). 
+Please ensure your project lead has approved with a +1 the request. 
 
+This integration will provide: 
+* A Develocity CI Bot with CI permission on the platform
+* Secrets integration with the Secrets Manager
+* Accessing secrets from any CI
+* Accessing Develocity platform from any CI
 
 ## CI integration
 
@@ -184,6 +272,25 @@ jobs:
             DEVELOCITY_ACCESS_KEY: ${{ secrets.DEVELOCITY_ACCESS_KEY }}
 ```
 
+## Authenticating to [develocity-staging.eclipse.org](https://develocity-staging.eclipse.org/)
+
+### CI Builds
+CI environments are most commonly configured to read access keys from an environment variable, stored as a secret. Onboarded Gradle and Maven CI builds will look for the environment variable `DEVELOCITY_ACCESS_KEY` and use its value to authenticate to [develocity-staging.eclipse.org](https://develocity-staging.eclipse.org/).
+
+### Local Builds
+
+In order to authenticate a local development machine, Develocity offers automated access key provisioning:
+
+- [Automated access key provisioning for Gradle builds](https://docs.gradle.com/develocity/gradle-plugin/current/#automated_access_key_provisioning) 
+- [Automated access key provisioning for Maven builds](https://docs.gradle.com/develocity/maven-extension/current/#automated_access_key_provisioning)
+
+When executed, the automated provisioning launches a web browser to [develocity-staging.eclipse.org](https://develocity-staging.eclipse.org/) and asks you to sign in. All Eclipse Foundation committers can log in using their Eclipse account: email / password.
+
+### Unauthenticated Builds
+
+Builds that are not authenticated to Develocity will simply not publish a Build Scan®. A lack of authentication will not cause the build to fail and will not be shown to the user. This includes builds by unauthenticated Eclipse committers, unauthenticated CI systems, or community contributors.
+
+
 ## Best practices
 
 ### Obfuscation