Prepare for first release (#15)

* Prepare for first release * Update RELEASING.md Co-authored-by: Mateusz Rzeszutek <[email protected]> --------- Co-authored-by: Mateusz Rzeszutek <[email protected]>
open-telemetry · Sep 1, 2023 · d81241f · d81241f
1 parent 6fe70cb
commit d81241f
Show file tree

Hide file tree

Showing 5 changed files with 120 additions and 20 deletions.
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -24,8 +24,8 @@ jobs:
       - name: Build and publish artifacts
         uses: gradle/gradle-build-action@v2
         with:
-          # TODO(jack-berg): add following arguments when confident in release process: closeAndReleaseSonatypeStagingRepository
-          arguments: assemble publishToSonatype
+          # TODO(jack-berg): remove closeSonatypeStagingRepository and add closeAndReleaseSonatypeStagingRepository when confident in release process
+          arguments: assemble publishToSonatype closeSonatypeStagingRepository
         env:
           SONATYPE_USER: ${{ secrets.SONATYPE_USER }}
           SONATYPE_KEY: ${{ secrets.SONATYPE_KEY }}

diff --git a/README.md b/README.md
@@ -1,18 +1,74 @@
-# 🚧 WARNING: Repository currently under construction 🚧
-
 # OpenTelemetry Semantic Conventions for Java
+[![Continuous Build][ci-image]][ci-url]
 
 Java code-generation for the [OpenTelemetry Semantic Conventions](https://github.com/open-telemetry/semantic-conventions).
 
+## Published released
+
+Published releases are available on maven central.
+
+TODO(jack-berg): insert maven badge indicating latest available release
+
+### Maven
+
+```xml
+<project>
+  <dependencies>
+    <dependency>
+      <groupId>io.opentelemetry.semconv</groupId>
+      <artifactId>opentelemetry-semconv</artifactId>
+      <version>{{version}}</version>
+    </dependency>
+  </dependencies>
+</project>
+```
+
+### Gradle
+
+```groovy
+dependencies {
+  implementation platform("io.opentelemetry.semconv:opentelemetry-semconv:{{version}}")
+}
+```
+
+## Requirements
+
+Java 17 or higher is required to build the projects in this repository. The built artifacts can be
+used on Java 8 or higher.
+
 ## Generating semantic conventions
 
-Prerequisites:
-- Docker
-- JDK 17+
+Requires docker.
 
 In a shell, execute the following gradle tasks:
 
 ```shell
 ./gradlew generateSemanticConventions --console=plain
 ./gradlew spotlessApply
 ```
+
+This will download the version
+of [open-telemetry/semantic-conventions](https://github.com/open-telemetry/semantic-conventions)
+defined in the `semanticConventionsVersion` variable of [build.gradle.kts](./build.gradle.kts) and
+generate semantic conventions classes from the release contents.
+
+## Contributing
+
+Before you start - see OpenTelemetry
+general [contributing](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md)
+requirements and recommendations.
+
+Make sure to review the projects [license](LICENSE) and sign
+the [CNCF CLA](https://identity.linuxfoundation.org/projects/cncf). A signed CLA will be enforced by
+an automatic check once you submit a PR, but you can also sign it after opening your PR.
+
+This repository is an extension
+of [open-telemetry/opentelemetry-java](https://github.com/open-telemetry/opentelemetry-java).
+See [opentelemetry-java contributors](https://github.com/open-telemetry/opentelemetry-java#contributing)
+for code owners.
+
+[ci-image]: https://github.com/open-telemetry/semantic-conventions-java/workflows/Build/badge.svg
+[ci-url]: https://github.com/open-telemetry/semantic-conventions-java/actions?query=workflow%3Abuild+branch%3Amain
+
+TODO(jack-berg): add code coverage badge?
+TODO(jack-berg): add maven badge after first release
diff --git a/RELEASING.md b/RELEASING.md
@@ -0,0 +1,39 @@
+# Release Process
+
+Releases are performed in lockstep
+with [open-telemetry/semantic-conventions](https://github.com/open-telemetry/semantic-conventions) [releases](https://github.com/open-telemetry/semantic-conventions/releases).
+
+## Preparing a new release
+
+Applies to major, minor and patch releases of `open-telemetry/semantic-conventions`.
+
+* Merge a PR to `main` with the following changes:
+  * Update the `CHANGELOG.md`
+    * The heading for the unreleased entries should be `## Unreleased`
+  * Bump the `semanticConventionsVersion` variable in `build.gradle.kts` to version
+    of `semantic-conventions` to be released
+  * Follow the instructions
+    to [generate the semantic conventions](README.md#generating-semantic-conventions)
+* Run
+  the [Prepare release branch workflow](https://github.com/open-telemetry/semantic-conventions-java/actions/workflows/prepare-release-branch.yml)
+  * Press the "Run workflow" button, and leave the default branch `main` selected
+  * Review and merge the two pull requests it creates (one is targeted to the release branch and one
+    is targeted to `main`)
+
+## Preparing a patch release
+
+TODO(jack-berg): Define process for releasing a patch, which should add a 4th component to
+the `semantic-convention` release version, e.g. `v1.21.0.1`
+
+## Making the release
+
+* Run
+  the [Release workflow](https://github.com/open-telemetry/semantic-conventions-java/actions/workflows/release.yml)
+  * Press the "Run workflow" button, then select the release branch from the dropdown list,
+    e.g. `release/v1.21.0`, and click the "Run workflow" button below that.
+  * This workflow will publish artifacts to maven central and will publish a GitHub release with
+    release notes based on the change log.
+
+## Credentials
+
+See [opentelemetry-java credentials](https://github.com/open-telemetry/opentelemetry-java/blob/main/RELEASING.md#credentials).
diff --git a/build.gradle.kts b/build.gradle.kts
@@ -25,18 +25,11 @@ var releaseVersion = semanticConventionsVersion + "-alpha"
 if (snapshot) {
   releaseVersion += "-SNAPSHOT"
 }
-version = releaseVersion
 
-dependencies {
-  implementation(platform("io.opentelemetry:opentelemetry-bom:1.29.0"))
-  implementation("io.opentelemetry:opentelemetry-api")
-
-  testImplementation(platform("org.junit:junit-bom:5.10.0"))
-  testImplementation("org.junit.jupiter:junit-jupiter-api")
-  testImplementation("org.junit.jupiter:junit-jupiter-engine")
-
-  testImplementation(platform("org.assertj:assertj-bom:3.24.2"))
-  testImplementation("org.assertj:assertj-core")
+base {
+  version = releaseVersion
+  description = "OpenTelemetry Semantic Conventions generated classes for Java"
+  archivesName.set("opentelemetry-semconv")
 }
 
 nexusPublishing {
@@ -60,6 +53,18 @@ nexusPublishing {
   }
 }
 
+dependencies {
+  implementation(platform("io.opentelemetry:opentelemetry-bom:1.29.0"))
+  implementation("io.opentelemetry:opentelemetry-api")
+
+  testImplementation(platform("org.junit:junit-bom:5.10.0"))
+  testImplementation("org.junit.jupiter:junit-jupiter-api")
+  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.18.0"
 val semanticConventionsRepoZip = "https://github.com/open-telemetry/semantic-conventions/archive/v$semanticConventionsVersion.zip"

diff --git a/buildSrc/src/main/kotlin/otel.java-conventions.gradle.kts b/buildSrc/src/main/kotlin/otel.java-conventions.gradle.kts
@@ -65,7 +65,7 @@ tasks {
   }
 
   withType<Javadoc>().configureEach {
-    exclude("io/opentelemetry/**/internal/**")
+    exclude("io/opentelemetry/semconv/**/internal/**")
 
     with(options as StandardJavadocDocletOptions) {
       source = "8"
@@ -86,7 +86,7 @@ tasks {
         "Automatic-Module-Name" to "io.opentelemetry.semconv",
         "Built-By" to System.getProperty("user.name"),
         "Built-JDK" to System.getProperty("java.version"),
-        "Implementation-Title" to project.name,
+        "Implementation-Title" to project.base.archivesName,
         "Implementation-Version" to project.version)
     }
   }