Address PR review comments

- Fix Gradle snippets: use implementation instead of platform() so
  transitive dependencies are actually added to the classpath
- Add explicit versions for OTel instrumentation dependencies since
  Maven dependencyManagement is not transitive to consumers
- Remove misleading claims about automatic version management in docs
- Add maven.compiler.release and project.build.sourceEncoding to all
  standalone example POMs (Java 8 for most, Java 17 for Tomcat 11)
- Update set-release-version-github-pages.sh description to reflect
  broader docs/content scope
- Document $version placeholder convention in CLAUDE.md

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

Author: zeitlinger

.mise/tasks/set-release-version-github-pages.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 
-#MISE description="Set release version in GitHub Pages quickstart.md"
+#MISE description="Set release version in all GitHub Pages docs"
 
 set -euox pipefail
 

CLAUDE.md

@@ -119,6 +119,12 @@ mise run lint:super-linter
 - Integration tests are in `integration-tests/` and run during `verify` phase
 - Acceptance tests use OATs framework: `mise run acceptance-test`
 
+## Documentation
+
+- Docs live under `docs/content/` and use `$version` as a placeholder for the library version
+- When publishing GitHub Pages, `mise run set-release-version-github-pages` replaces `$version` with the latest git tag across all `docs/content/**/*.md` files (the published site is not versioned)
+- When writing docs, always use `$version` for the Prometheus client version — never hardcode it
+
 ## Java Version
 
 Source compatibility: Java 8. Tests run on Java 25 (configured in `mise.toml`).

docs/content/otel/jvm-runtime-metrics.md

@@ -32,13 +32,11 @@ the runtime-telemetry instrumentation:
 {{< tab "Gradle" >}}
 
 ```groovy
-implementation platform('io.prometheus:prometheus-metrics-otel-support:$version')
+implementation 'io.prometheus:prometheus-metrics-otel-support:$version'
 
-// Pick ONE of the following:
-// Java 8+:
-implementation 'io.opentelemetry.instrumentation:opentelemetry-runtime-telemetry-java8'
-// Java 17+ (adds JFR-based metrics):
-// implementation 'io.opentelemetry.instrumentation:opentelemetry-runtime-telemetry-java17'
+// Use opentelemetry-runtime-telemetry-java8 (Java 8+)
+// or opentelemetry-runtime-telemetry-java17 (Java 17+, JFR-based)
+implementation 'io.opentelemetry.instrumentation:opentelemetry-runtime-telemetry-java8:2.24.0-alpha'
 ```
 
 {{< /tab >}}
@@ -57,12 +55,14 @@ implementation 'io.opentelemetry.instrumentation:opentelemetry-runtime-telemetry
 <dependency>
     <groupId>io.opentelemetry.instrumentation</groupId>
     <artifactId>opentelemetry-runtime-telemetry-java8</artifactId>
+    <version>2.24.0-alpha</version>
 </dependency>
 <!-- Java 17+ (adds JFR-based metrics) -->
 <!--
 <dependency>
     <groupId>io.opentelemetry.instrumentation</groupId>
     <artifactId>opentelemetry-runtime-telemetry-java17</artifactId>
+    <version>2.24.0-alpha</version>
 </dependency>
 -->
 ```

docs/content/otel/support.md

@@ -5,8 +5,7 @@ weight: 2
 
 The `prometheus-metrics-otel-support` module bundles the
 OpenTelemetry SDK and the Prometheus exporter into a single
-POM dependency. It also imports the OTel instrumentation BOM
-so that version management is handled automatically.
+POM dependency.
 
 Use this module when you want to combine OpenTelemetry
 instrumentations (e.g. JVM runtime metrics) with the
@@ -18,7 +17,7 @@ Prometheus Java client on one `/metrics` endpoint.
 {{< tab "Gradle" >}}
 
 ```groovy
-implementation platform('io.prometheus:prometheus-metrics-otel-support:$version')
+implementation 'io.prometheus:prometheus-metrics-otel-support:$version'
 ```
 
 {{< /tab >}}
@@ -41,11 +40,6 @@ This single dependency replaces:
 - `io.opentelemetry:opentelemetry-sdk`
 - `io.opentelemetry:opentelemetry-exporter-prometheus`
 
-It also imports the `opentelemetry-instrumentation-bom-alpha`
-so you can add OTel instrumentation modules (like
-`opentelemetry-runtime-telemetry-java8`) without specifying
-their version.
-
 ## Use Cases
 
 See [JVM Runtime Metrics]({{< relref "jvm-runtime-metrics.md" >}})

examples/example-custom-buckets/pom.xml

@@ -7,6 +7,11 @@
   <artifactId>example-custom-buckets</artifactId>
   <version>1.0-SNAPSHOT</version>
 
+  <properties>
+    <maven.compiler.release>8</maven.compiler.release>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+  </properties>
+
   <name>Example - Custom Buckets</name>
   <description>
     End-to-End example of Native Histograms with Custom Buckets (NHCB): Java app -&gt; Prometheus -&gt; Grafana

examples/example-exemplars-tail-sampling/example-greeting-service/pom.xml

@@ -8,6 +8,11 @@
   <artifactId>example-greeting-service</artifactId>
   <version>1.0-SNAPSHOT</version>
 
+  <properties>
+    <maven.compiler.release>17</maven.compiler.release>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+  </properties>
+
   <name>Example - OpenTelemetry Exemplars - Greeting Service</name>
   <description>
     Part of a distributed "Hello, World" REST service to show Exemplars with OpenTelemetry's distributed

examples/example-exemplars-tail-sampling/example-hello-world-app/pom.xml

@@ -8,6 +8,11 @@
   <artifactId>example-hello-world-app</artifactId>
   <version>1.0-SNAPSHOT</version>
 
+  <properties>
+    <maven.compiler.release>17</maven.compiler.release>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+  </properties>
+
   <name>Example - OpenTelemetry Exemplars - Hello World App</name>
   <description>
     Part of a distributed "Hello, World" REST service to show Exemplars with OpenTelemetry's distributed

examples/example-exporter-httpserver/pom.xml

@@ -8,6 +8,11 @@
   <artifactId>example-exporter-httpserver</artifactId>
   <version>1.0-SNAPSHOT</version>
 
+  <properties>
+    <maven.compiler.release>8</maven.compiler.release>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+  </properties>
+
   <name>Example - HTTPServer Exporter</name>
   <description>
     Prometheus Metrics Example using the HTTPServer for exposing the metrics endpoint

examples/example-exporter-multi-target/pom.xml

@@ -8,6 +8,11 @@
   <artifactId>example-exporter-multi-target</artifactId>
   <version>1.0-SNAPSHOT</version>
 
+  <properties>
+    <maven.compiler.release>8</maven.compiler.release>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+  </properties>
+
   <name>Example - HTTPServer Exporter Multi Target</name>
   <description>
     Prometheus Metrics Example for multi-target pattern implementation

examples/example-exporter-opentelemetry/pom.xml

@@ -8,6 +8,11 @@
   <artifactId>example-exporter-opentelemetry</artifactId>
   <version>1.0-SNAPSHOT</version>
 
+  <properties>
+    <maven.compiler.release>8</maven.compiler.release>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+  </properties>
+
   <name>Example - OpenTelemetry Metrics Exporter</name>
   <description>
     Example of exposing metrics in OpenTelemetry format and pushing them to an OpenTelemetry collector