Split out incubating artifact (#41)

* Add dependencyManagement * Breaking out incubating artifact * Add check for schema urls * Fix automatic module name * Update readme * Revert to using 0.23.0 of generator * Fix check for diff check * PR feedback * Add availability test for incubating classes
open-telemetry · Feb 8, 2024 · 0141bda · 0141bda
1 parent 2be178a
commit 0141bda
Show file tree

Hide file tree

Showing 19 changed files with 675 additions and 2,374 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -71,7 +71,8 @@ jobs:
       - name: Check for diff
         run: |
           # need to "git add" in case any generated files did not already exist
-          git add src
+          # select files from both /semconv and /semconv-incubating
+          git add semconv**
           if git diff --cached --quiet
           then 
             echo "No diff detected."

diff --git a/README.md b/README.md
@@ -15,11 +15,18 @@ Published releases are available on maven central. Replace `{{version}}` with th
 ```xml
 <project>
   <dependencies>
+    <!-- Stable semantic conventions. Note: generated code is still subject to breaking changes while published with "-alpha" suffix. -->
     <dependency>
       <groupId>io.opentelemetry.semconv</groupId>
       <artifactId>opentelemetry-semconv</artifactId>
       <version>{{version}}</version>
     </dependency>
+    <!-- Incubating semantic conventions. Breaking changes expected. Library instrumentation SHOULD NOT depend on this. -->
+    <dependency>
+      <groupId>io.opentelemetry.semconv</groupId>
+      <artifactId>opentelemetry-semconv-incubating</artifactId>
+      <version>{{version}}</version>
+    </dependency>
   </dependencies>
 </project>
 ```
@@ -28,7 +35,10 @@ Published releases are available on maven central. Replace `{{version}}` with th
 
 ```groovy
 dependencies {
+  // Stable semantic conventions. Note: generated code is still subject to breaking changes while published with "-alpha" suffix.
   implementation "io.opentelemetry.semconv:opentelemetry-semconv:{{version}}"
+  // Incubating semantic conventions. Breaking changes expected. Library instrumentation SHOULD NOT depend on this.
+  implementation "io.opentelemetry.semconv:opentelemetry-semconv-incubating:{{version}}"
 }
 ```
 
@@ -37,7 +47,7 @@ dependencies {
 Java 17 or higher is required to build the projects in this repository. The built artifacts can be
 used on Java 8 or higher.
 
-To use this artifact you must also depend on `io.opentelemetry:opentelemetry-api:{{version}}`.
+To use these artifacts, you must also depend on `io.opentelemetry:opentelemetry-api:{{version}}`.
 See [opentelemetry-java releases](https://github.com/open-telemetry/opentelemetry-java#releases) for
 more information.
 
@@ -57,6 +67,8 @@ of [open-telemetry/semantic-conventions](https://github.com/open-telemetry/seman
 defined in the `semanticConventionsVersion` variable of [build.gradle.kts](./build.gradle.kts) and
 generate semantic conventions classes from the release contents.
 
+TODO: Update the following paragraph with new strategy for managing compatibility
+
 This repository publishes `-alpha` artifacts and as discussed
 in [opentelemetry-java/VERSIONING.md](https://github.com/open-telemetry/opentelemetry-java/blob/main/VERSIONING.md),
 we make no compatibility guarantees. However, by convention we've been keeping attribute constants

diff --git a/build.gradle.kts b/build.gradle.kts
@@ -2,12 +2,6 @@ import de.undercouch.gradle.tasks.download.Download
 import java.time.Duration
 
 plugins {
-  id("otel.java-conventions")
-  id("otel.publish-conventions")
-  id("otel.japicmp-conventions")
-
-  id("otel.animalsniffer-conventions")
-
   id("de.undercouch.download")
   id("io.github.gradle-nexus.publish-plugin")
 }
@@ -18,6 +12,7 @@ val snapshot = true
 
 // The release version of https://github.com/open-telemetry/semantic-conventions used to generate classes
 var semanticConventionsVersion = "1.23.1"
+val schemaUrlVersions = listOf(semanticConventionsVersion, "1.22.0")
 
 // Compute the artifact version, which includes the "-alpha" suffix and includes "-SNAPSHOT" suffix if not releasing
 // Release example: version=1.21.0-alpha
@@ -27,10 +22,8 @@ if (snapshot) {
   releaseVersion += "-SNAPSHOT"
 }
 
-base {
+allprojects {
   version = releaseVersion
-  description = "OpenTelemetry Semantic Conventions generated classes for Java"
-  archivesName.set("opentelemetry-semconv")
 }
 
 nexusPublishing {
@@ -54,22 +47,6 @@ nexusPublishing {
   }
 }
 
-val opentelemetryJavaVersion = "1.31.0"
-
-dependencies {
-  compileOnly("io.opentelemetry:opentelemetry-api:$opentelemetryJavaVersion")
-
-  testImplementation("io.opentelemetry:opentelemetry-api:$opentelemetryJavaVersion")
-
-  testImplementation(platform("org.junit:junit-bom:5.10.0"))
-  testImplementation("org.junit.jupiter:junit-jupiter-api")
-  testImplementation("org.junit.jupiter:junit-jupiter-params")
-  testImplementation("org.junit.jupiter:junit-jupiter-engine")
-
-  testImplementation(platform("org.assertj:assertj-bom:3.24.2"))
-  testImplementation("org.assertj:assertj-core")
-}
-
 // start - define tasks to download, unzip, and generate from opentelemetry/semantic-conventions
 var generatorVersion = "0.23.0"
 val semanticConventionsRepoZip = "https://github.com/open-telemetry/semantic-conventions/archive/v$semanticConventionsVersion.zip"
@@ -93,50 +70,66 @@ val unzipConfigurationSchema by tasks.registering(Copy::class) {
   into("$buildDir/semantic-conventions/")
 }
 
-val generateSemanticAttributes by tasks.registering(Exec::class) {
-  dependsOn(unzipConfigurationSchema)
-
-  standardOutput = System.out
-  executable = "docker"
-  setArgs(listOf(
-    "run",
-    "--rm",
-    "-v", "$buildDir/semantic-conventions/model:/source",
-    "-v", "$projectDir/buildscripts/templates:/templates",
-    "-v", "$projectDir/src/main/java/io/opentelemetry/semconv/:/output",
-    "otel/semconvgen:$generatorVersion",
-    "--only", "span,event,attribute_group,scope,metric",
-    "--yaml-root", "/source", "code",
-    "--template", "/templates/SemanticAttributes.java.j2",
-    "--output", "/output/SemanticAttributes.java",
-    "-Dclass=SemanticAttributes",
-    "-DschemaUrl=$schemaUrl",
-    "-Dpkg=io.opentelemetry.semconv"))
+fun generateTask(taskName: String, resource: Boolean, incubating: Boolean) {
+  tasks.register(taskName, Exec::class) {
+    dependsOn(unzipConfigurationSchema)
+
+    standardOutput = System.out
+    executable = "docker"
+
+    val onlyArg = if (resource) "resource" else "span,event,attribute_group,scope,metric"
+    val classNamePrefix = if (incubating) "Incubating" else ""
+    var className = if (resource) "${classNamePrefix}ResourceAttributes" else "${classNamePrefix}SemanticAttributes"
+    val outputDir = if (incubating) "semconv-incubating/src/main/java/io/opentelemetry/semconv/incubating/" else "semconv/src/main/java/io/opentelemetry/semconv/"
+    val stability = if (incubating) "StabilityLevel.EXPERIMENTAL" else "StabilityLevel.STABLE"
+    val packageNameArg = if (incubating) "io.opentelemetry.semconv.incubating" else "io.opentelemetry.semconv"
+
+    setArgs(listOf(
+        "run",
+        "--rm",
+        "-v", "$buildDir/semantic-conventions/model:/source",
+        "-v", "$projectDir/buildscripts/templates:/templates",
+        "-v", "$projectDir/$outputDir:/output",
+        "otel/semconvgen:$generatorVersion",
+        "--only", onlyArg,
+        "--yaml-root", "/source", "code",
+        "--template", "/templates/SemanticAttributes.java.j2",
+        "--output", "/output/$className.java",
+        "-Dclass=$className",
+        "-Dstability=${stability}",
+        "-Dpkg=$packageNameArg"))
+  }
 }
 
-val generateResourceAttributes by tasks.registering(Exec::class) {
-  dependsOn(unzipConfigurationSchema)
-
-  standardOutput = System.out
-  executable = "docker"
-  setArgs(listOf(
-    "run",
-    "--rm",
-    "-v", "$buildDir/semantic-conventions/model:/source",
-    "-v", "$projectDir/buildscripts/templates:/templates",
-    "-v", "$projectDir/src/main/java/io/opentelemetry/semconv/:/output",
-    "otel/semconvgen:$generatorVersion",
-    "--only", "resource",
-    "--yaml-root", "/source", "code",
-    "--template", "/templates/SemanticAttributes.java.j2",
-    "--output", "/output/ResourceAttributes.java",
-    "-Dclass=ResourceAttributes",
-    "-DschemaUrl=$schemaUrl",
-    "-Dpkg=io.opentelemetry.semconv"))
+generateTask("generateStableSemanticAttributes", false, false)
+generateTask("generateIncubatingSemanticAttributes", false, true)
+generateTask("generateStableResourceAttributes", true, false)
+generateTask("generateIncubatingResourceAttributes", true, true)
+
+tasks.register("checkSchemaUrls") {
+  val schemaUrlsClass = File("$projectDir/semconv/src/main/java/io/opentelemetry/semconv/SchemaUrls.java")
+  if (!schemaUrlsClass.exists()) {
+    throw GradleException("SchemaUrls file does not exist")
+  }
+
+  for (schemaUrlVersion: String in schemaUrlVersions) {
+    val expectedLine = "public static final String V" + schemaUrlVersion.replace(".", "_") + " = \"https://opentelemetry.io/schemas/" + schemaUrlVersion + "\";"
+    if (!schemaUrlsClass.readLines().any { it.contains(expectedLine) }) {
+      throw GradleException("SchemaUrls file does not contain: $expectedLine")
+    }
+  }
 }
 
 val generateSemanticConventions by tasks.registering {
-  dependsOn(generateSemanticAttributes)
-  dependsOn(generateResourceAttributes)
+  dependsOn(tasks.getByName("generateStableSemanticAttributes"))
+  dependsOn(tasks.getByName("generateIncubatingSemanticAttributes"))
+  dependsOn(tasks.getByName("generateStableResourceAttributes"))
+  dependsOn(tasks.getByName("generateIncubatingResourceAttributes"))
+  dependsOn(tasks.getByName("checkSchemaUrls"))
+}
+
+tasks.register("build") {
+  dependsOn(tasks.getByName("checkSchemaUrls"))
 }
+
 // end
diff --git a/buildSrc/src/main/kotlin/io/opentelemetry/gradle/OtelJavaExtension.kt b/buildSrc/src/main/kotlin/io/opentelemetry/gradle/OtelJavaExtension.kt
@@ -0,0 +1,12 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.gradle
+
+import org.gradle.api.provider.Property
+
+abstract class OtelJavaExtension {
+    abstract val moduleName: Property<String>
+}
diff --git a/buildSrc/src/main/kotlin/otel.java-conventions.gradle.kts b/buildSrc/src/main/kotlin/otel.java-conventions.gradle.kts
@@ -1,3 +1,4 @@
+import io.opentelemetry.gradle.OtelJavaExtension
 import org.gradle.api.tasks.testing.logging.TestExceptionFormat
 
 plugins {
@@ -10,6 +11,8 @@ plugins {
   id("otel.spotless-conventions")
 }
 
+val otelJava = extensions.create<OtelJavaExtension>("otelJava")
+
 java {
   toolchain {
     languageVersion.set(JavaLanguageVersion.of(17))
@@ -81,9 +84,11 @@ tasks {
   }
 
   withType<Jar>().configureEach {
+    inputs.property("moduleName", otelJava.moduleName)
+
     manifest {
       attributes(
-        "Automatic-Module-Name" to "io.opentelemetry.semconv",
+          "Automatic-Module-Name" to otelJava.moduleName,
         "Built-By" to System.getProperty("user.name"),
         "Built-JDK" to System.getProperty("java.version"),
         "Implementation-Title" to project.base.archivesName,
@@ -108,3 +113,34 @@ configurations.configureEach {
     preferProjectModules()
   }
 }
+
+val dependencyManagement by configurations.creating {
+  isCanBeConsumed = false
+  isCanBeResolved = false
+  isVisible = false
+}
+
+dependencies {
+  dependencyManagement(platform(project(":dependencyManagement")))
+  afterEvaluate {
+    configurations.configureEach {
+      if (isCanBeResolved && !isCanBeConsumed) {
+        extendsFrom(dependencyManagement)
+      }
+    }
+  }
+}
+
+testing {
+  suites.withType(JvmTestSuite::class).configureEach {
+    dependencies {
+      implementation(project(project.path))
+
+      implementation("org.junit.jupiter:junit-jupiter-api")
+      implementation("org.junit.jupiter:junit-jupiter-params")
+      runtimeOnly("org.junit.jupiter:junit-jupiter-engine")
+
+      implementation("org.assertj:assertj-core")
+    }
+  }
+}