document how to use the BOM (#1198)

* document how to use the BOM Signed-off-by: Gregor Zeitlinger <[email protected]> * set latest release Signed-off-by: Gregor Zeitlinger <[email protected]> * set latest release Signed-off-by: Gregor Zeitlinger <[email protected]> --------- Signed-off-by: Gregor Zeitlinger <[email protected]>
prometheus · Nov 11, 2024 · 7757e9d · 7757e9d
1 parent d21b6c3
commit 7757e9d
Show file tree

Hide file tree

Showing 3 changed files with 102 additions and 7 deletions.
diff --git a/.github/workflows/github-pages.yaml b/.github/workflows/github-pages.yaml
@@ -34,12 +34,16 @@ jobs:
       HUGO_VERSION: 0.115.4
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-tags: 'true'
       - name: Set up JDK
         uses: actions/setup-java@v4
         with:
           java-version: 17
           distribution: temurin
           cache: 'maven'
+      - name: Set release version
+        run: ./scripts/set-release-version-github-pages.sh
       - name: Install Hugo CLI
         run: |
           wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \

diff --git a/docs/content/getting-started/quickstart.md b/docs/content/getting-started/quickstart.md
@@ -1,6 +1,6 @@
 ---
 title: Quickstart
-weight: 1
+weight: 0
 ---
 
 This tutorial shows the quickest way to get started with the Prometheus Java metrics library.
@@ -15,34 +15,118 @@ We use the following dependencies:
 {{< tabs "uniqueid" >}}
 {{< tab "Gradle" >}}
 ```
-implementation 'io.prometheus:prometheus-metrics-core:1.0.0'
-implementation 'io.prometheus:prometheus-metrics-instrumentation-jvm:1.0.0'
-implementation 'io.prometheus:prometheus-metrics-exporter-httpserver:1.0.0'
+implementation 'io.prometheus:prometheus-metrics-core:$version'
+implementation 'io.prometheus:prometheus-metrics-instrumentation-jvm:$version'
+implementation 'io.prometheus:prometheus-metrics-exporter-httpserver:$version'
 ```
 {{< /tab >}}
 {{< tab "Maven" >}}
 ```xml
 <dependency>
     <groupId>io.prometheus</groupId>
     <artifactId>prometheus-metrics-core</artifactId>
-    <version>1.0.0</version>
+    <version>$version</version>
 </dependency>
 <dependency>
     <groupId>io.prometheus</groupId>
     <artifactId>prometheus-metrics-instrumentation-jvm</artifactId>
-    <version>1.0.0</version>
+    <version>$version</version>
 </dependency>
 <dependency>
     <groupId>io.prometheus</groupId>
     <artifactId>prometheus-metrics-exporter-httpserver</artifactId>
-    <version>1.0.0</version>
+    <version>$version</version>
 </dependency>
 ```
 {{< /tab >}}
 {{< /tabs >}}
 
 There are alternative exporters as well, for example if you are using a Servlet container like Tomcat or Undertow you might want to use `prometheus-exporter-servlet-jakarta` rather than a standalone HTTP server.
 
+# Dependency management
+
+A Bill of Material
+([BOM](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#bill-of-materials-bom-poms))
+ensures that versions of dependencies (including transitive ones) are aligned.
+This is especially important when using Spring Boot, which manages some of the dependencies of the project.
+
+You should omit the version number of the dependencies in your build file if you are using a BOM.
+
+{{< tabs "uniqueid" >}}
+{{< tab "Gradle" >}}
+
+You have two ways to import a BOM.
+
+First, you can use the Gradle’s native BOM support by adding `dependencies`:
+
+```kotlin
+import org.springframework.boot.gradle.plugin.SpringBootPlugin
+
+plugins {
+  id("java")
+  id("org.springframework.boot") version "3.2.O" // if you are using Spring Boot
+}
+
+dependencies {
+  implementation(platform(SpringBootPlugin.BOM_COORDINATES)) // if you are using Spring Boot
+  implementation(platform("io.prometheus:prometheus-metrics-bom:$version"))
+}
+```
+
+The other way with Gradle is to use `dependencyManagement`:
+
+```kotlin
+plugins {
+  id("java")
+  id("org.springframework.boot") version "3.2.O" // if you are using Spring Boot
+  id("io.spring.dependency-management") version "1.1.0" // if you are using Spring Boot
+}
+
+dependencyManagement {
+  imports {
+    mavenBom("io.prometheus:prometheus-metrics-bom:$version")
+  }
+}
+```
+
+{{% alert title="Note" color="info" %}}
+
+Be careful not to mix up the different ways of configuring things with Gradle.
+For example, don't use
+`implementation(platform("io.prometheus:prometheus-metrics-bom:$version"))`
+with the `io.spring.dependency-management` plugin.
+
+{{% /alert %}}    
+
+{{< /tab >}}
+{{< tab "Maven" >}}
+
+{{% alert title="Note" color="info" %}}
+
+Import the Prometheus Java metrics BOMs before any other BOMs in your
+project. For example, if you import the `spring-boot-dependencies` BOM, you have
+to declare it after the Prometheus Java metrics BOMs.
+
+{{% /alert %}}
+
+The following example shows how to import the Prometheus Java metrics BOMs using Maven:
+
+```xml
+<dependencyManagement>
+    <dependencies>
+        <dependency>
+            <groupId>io.prometheus</groupId>
+            <artifactId>prometheus-metrics-bom</artifactId>
+            <version>$version</version>
+            <type>pom</type>
+            <scope>import</scope>
+        </dependency>
+    </dependencies>
+</dependencyManagement>
+```
+
+{{< /tab >}}
+{{< /tabs >}}
 
 # Example Application
 

diff --git a/scripts/set-release-version-github-pages.sh b/scripts/set-release-version-github-pages.sh
@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+version=$(git tag -l | grep 'v' | sort | tail -1 | sed 's/v//')
+marker="\$version"
+sed -i "s/$marker/$version/g" docs/content/getting-started/quickstart.md