Update docs for the 1.2.0 release (#3213)

* Update the changelog for version 1.2.0

* Update the README for version 1.2.0

* Update docs to include instructions related to API diffs.

* Add the diffs from 1.1.0

* tweak the japicmp task a bit and update the current diffs

* update the website docs to point at 1.2.0

* Add instructions about updating the website docs.

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased:
 
+---
+
+## Version 1.2.0 - 2021-05-07
+
 ### General
 
 #### Enhancements
@@ -32,6 +36,12 @@ previously used `"unknown"` value. This change is based on a specification clari
 #### Bugfixes
 - The B3 Propagator injectors now only include the relevant fields for the specific injection format.
 
+#### Behavioral Changes
+- The `W3CBaggagePropagator` will no longer explicitly populate an empty `Baggage` instance into the context when
+the header is unparsable. It will now return the provided Context instance unaltered, as is required by the specification.
+- The `AwsXrayPropagator` will no longer explicitly populate an invalid `Span` instance into the context when
+the headers are unparsable. It will now return the provided Context instance unaltered, as is required by the specification.
+
 ### Exporters
 - The `jaeger-thrift` exporter has had its dependency on the `jaeger-client` library updated to version `1.6.0`.
 - The `zipkin` exporter now has an option to specific a custom timeout. 
@@ -59,6 +69,8 @@ of a batch SpanProcessor allows you to provide your own ExecutorService to do th
 a system property (`otel.exporter.jaeger.timeout`) or environment variable (`OTEL_EXPORTER_JAEGER_TIMEOUT`).
 - The `autoconfigure` module now supports providing the timeout setting for the Zipkin exporter via 
 a system property (`otel.exporter.zipkin.timeout`) or environment variable (`OTEL_EXPORTER_ZIPKIN_TIMEOUT`).
+- The `autoconfigure` module now exposes the `EnvironmentResource` class to provide programmatic access to a `Resource`
+built from parsing the `otel.resource.attributes` configuration property.
 
 ### Metrics (alpha)
 

CONTRIBUTING.md

@@ -50,6 +50,10 @@ with the `check` task.
 ```bash
 $ ./gradlew check
 ```
+
+Note: this gradle task will potentially generate changes to files in the `docs/apidiffs/current_vs_latest`
+directory. Please make sure to include any changes to these files in your pull request.
+
 ## PR Review
 After you submit a PR, it will be reviewed by the project maintainers and approvers. Not all maintainers need to review a
 particular PR, but merging to the base branch is authorized to restricted members (administrators).

README.md

@@ -83,7 +83,7 @@ dependency versions in sync.
       <dependency>
         <groupId>io.opentelemetry</groupId>
         <artifactId>opentelemetry-bom</artifactId>
-        <version>1.1.0</version>
+        <version>1.2.0</version>
         <type>pom</type>
         <scope>import</scope>
       </dependency>
@@ -102,7 +102,7 @@ dependency versions in sync.
 
 ```groovy
 dependencies {
-  implementation platform("io.opentelemetry:opentelemetry-bom:1.1.0")
+  implementation platform("io.opentelemetry:opentelemetry-bom:1.2.0")
   implementation('io.opentelemetry:opentelemetry-api')
 }
 ```
@@ -127,7 +127,7 @@ We strongly recommend using our published BOM to keep all dependency versions in
       <dependency>
         <groupId>io.opentelemetry</groupId>
         <artifactId>opentelemetry-bom</artifactId>
-        <version>1.2.0-SNAPSHOT</version>
+        <version>1.3.0-SNAPSHOT</version>
         <type>pom</type>
         <scope>import</scope>
       </dependency>
@@ -150,7 +150,7 @@ repositories {
 }
 
 dependencies {
-  implementation platform("io.opentelemetry:opentelemetry-bom:1.2.0-SNAPSHOT")
+  implementation platform("io.opentelemetry:opentelemetry-bom:1.3.0-SNAPSHOT")
   implementation('io.opentelemetry:opentelemetry-api')
 }
 ```
@@ -170,19 +170,19 @@ This is a **current** feature status list:
 
 | Component                   | Version |
 | --------------------------- | ------- |
-| Trace API                   | v<!--VERSION_STABLE-->1.1.0<!--/VERSION_STABLE-->  |
-| Trace SDK                   | v<!--VERSION_STABLE-->1.1.0<!--/VERSION_STABLE-->  |
-| Context                     | v<!--VERSION_STABLE-->1.1.0<!--/VERSION_STABLE-->  |
-| Baggage                     | v<!--VERSION_STABLE-->1.1.0<!--/VERSION_STABLE-->  |
-| Jaeger Trace Exporter       | v<!--VERSION_STABLE-->1.1.0<!--/VERSION_STABLE-->  |
-| Zipkin Trace Exporter       | v<!--VERSION_STABLE-->1.1.0<!--/VERSION_STABLE-->  |
-| OTLP Exporter (Spans)       | v<!--VERSION_STABLE-->1.1.0<!--/VERSION_STABLE-->  |
-| OTLP Exporter (Metrics)     | v<!--VERSION_UNSTABLE-->1.1.0-alpha<!--/VERSION_UNSTABLE-->  |
-| Metrics API                 | v<!--VERSION_UNSTABLE-->1.1.0-alpha<!--/VERSION_UNSTABLE-->  |
-| Metrics SDK                 | v<!--VERSION_UNSTABLE-->1.1.0-alpha<!--/VERSION_UNSTABLE-->  |
-| Prometheus Metrics Exporter | v<!--VERSION_UNSTABLE-->1.1.0-alpha<!--/VERSION_UNSTABLE-->  |
-| OpenTracing Bridge          | v<!--VERSION_UNSTABLE-->1.1.0-alpha<!--/VERSION_UNSTABLE-->  |
-| OpenCensus Bridge           | v<!--VERSION_UNSTABLE-->1.1.0-alpha<!--/VERSION_UNSTABLE-->  |
+| Trace API                   | v<!--VERSION_STABLE-->1.2.0<!--/VERSION_STABLE-->  |
+| Trace SDK                   | v<!--VERSION_STABLE-->1.2.0<!--/VERSION_STABLE-->  |
+| Context                     | v<!--VERSION_STABLE-->1.2.0<!--/VERSION_STABLE-->  |
+| Baggage                     | v<!--VERSION_STABLE-->1.2.0<!--/VERSION_STABLE-->  |
+| Jaeger Trace Exporter       | v<!--VERSION_STABLE-->1.2.0<!--/VERSION_STABLE-->  |
+| Zipkin Trace Exporter       | v<!--VERSION_STABLE-->1.2.0<!--/VERSION_STABLE-->  |
+| OTLP Exporter (Spans)       | v<!--VERSION_STABLE-->1.2.0<!--/VERSION_STABLE-->  |
+| OTLP Exporter (Metrics)     | v<!--VERSION_UNSTABLE-->1.2.0-alpha<!--/VERSION_UNSTABLE-->  |
+| Metrics API                 | v<!--VERSION_UNSTABLE-->1.2.0-alpha<!--/VERSION_UNSTABLE-->  |
+| Metrics SDK                 | v<!--VERSION_UNSTABLE-->1.2.0-alpha<!--/VERSION_UNSTABLE-->  |
+| Prometheus Metrics Exporter | v<!--VERSION_UNSTABLE-->1.2.0-alpha<!--/VERSION_UNSTABLE-->  |
+| OpenTracing Bridge          | v<!--VERSION_UNSTABLE-->1.2.0-alpha<!--/VERSION_UNSTABLE-->  |
+| OpenCensus Bridge           | v<!--VERSION_UNSTABLE-->1.2.0-alpha<!--/VERSION_UNSTABLE-->  |
 
 See the project [milestones](https://github.com/open-telemetry/opentelemetry-java/milestones)
 for details on upcoming releases. The dates and features described in issues

RELEASING.md

@@ -2,6 +2,10 @@
 
 ## Starting the Release
 
+Before releasing, it is a good idea to run `./gradlew japicmp` on the main branch
+and verify that there are no unexpected public API changes seen in the `docs/apidiffs/current_vs_latest`
+directory.
+
 Open the release build workflow in your browser [here](https://github.com/open-telemetry/opentelemetry-java/actions/workflows/release-build.yml).
 
 You will see a button that says "Run workflow". Press the button, enter the version number you want
@@ -31,13 +35,21 @@ After releasing is done, you need to first update the docs.
 
 ```
 ./gradlew updateVersionInDocs -Prelease.version=x.y.z
+./gradlew japicmp -PapiBaseVersion=a.b.c -PapiNewVersion=x.y.z
+./gradlew japicmp
 ```
 
+Where `x.y.z` is the version just released and `a.b.c` is the previous version.
+
 Next, update the
 [CHANGELOG.md](https://github.com/open-telemetry/opentelemetry-java/blob/main/CHANGELOG.md).
 
 Create a PR to mark the new release in README.md and CHANGELOG.md on the main branch.
 
+Finally, update the files `website_docs` directory to point at the newly released version. Once that has
+been merged to the main branch, use the "Update OpenTelemetry Website" github action to create a PR 
+in the website repository with the changes.
+
 ## Patch Release
 
 All patch releases should include only bug-fixes, and must avoid

build.gradle.kts

@@ -57,10 +57,11 @@ fun Project.findArtifact(version: String) : File {
 val latestReleasedVersion : String by lazy {
     // hack to find the current released version of the project
     val temp: Configuration = project.configurations.create("tempConfig")
-    // pick the bom, since it's always there.
-    dependencies.add("tempConfig", "io.opentelemetry:opentelemetry-bom:latest.release")
+    // pick the api, since it's always there.
+    dependencies.add("tempConfig", "io.opentelemetry:opentelemetry-api:latest.release")
     val moduleVersion = project.configurations["tempConfig"].resolvedConfiguration.firstLevelModuleDependencies.elementAt(0).moduleVersion
     project.configurations.remove(temp)
+    println("Discovered latest release version: " + moduleVersion)
     moduleVersion
 }
 

docs/apidiffs/1.2.0_vs_1.1.0/opentelemetry-api.txt

@@ -0,0 +1,7 @@
+Comparing source compatibility of  against 
+***! MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.api.trace.Span  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++! NEW METHOD: PUBLIC(+) io.opentelemetry.api.trace.Span setAllAttributes(io.opentelemetry.api.common.Attributes)
+***! MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.api.trace.SpanBuilder  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++! NEW METHOD: PUBLIC(+) io.opentelemetry.api.trace.SpanBuilder setAllAttributes(io.opentelemetry.api.common.Attributes)

docs/apidiffs/1.2.0_vs_1.1.0/opentelemetry-context.txt

@@ -0,0 +1,2 @@
+Comparing source compatibility of  against 
+No changes.

docs/apidiffs/1.2.0_vs_1.1.0/opentelemetry-exporter-jaeger-thrift.txt

@@ -0,0 +1,2 @@
+Comparing source compatibility of  against 
+No changes.

docs/apidiffs/1.2.0_vs_1.1.0/opentelemetry-exporter-jaeger.txt

@@ -0,0 +1,2 @@
+Comparing source compatibility of  against 
+No changes.

docs/apidiffs/1.2.0_vs_1.1.0/opentelemetry-exporter-logging-otlp.txt

@@ -0,0 +1,2 @@
+Comparing source compatibility of  against 
+No changes.

docs/apidiffs/1.2.0_vs_1.1.0/opentelemetry-exporter-logging.txt

@@ -0,0 +1,2 @@
+Comparing source compatibility of  against 
+No changes.

docs/apidiffs/1.2.0_vs_1.1.0/opentelemetry-exporter-otlp-common.txt

@@ -0,0 +1,2 @@
+Comparing source compatibility of  against 
+No changes.

docs/apidiffs/1.2.0_vs_1.1.0/opentelemetry-exporter-otlp-trace.txt

@@ -0,0 +1,2 @@
+Comparing source compatibility of  against 
+No changes.

docs/apidiffs/1.2.0_vs_1.1.0/opentelemetry-exporter-otlp.txt

@@ -0,0 +1,2 @@
+Comparing source compatibility of  against 
+No changes.

docs/apidiffs/1.2.0_vs_1.1.0/opentelemetry-exporter-zipkin.txt

@@ -0,0 +1,5 @@
+Comparing source compatibility of  against 
+***  MODIFIED CLASS: PUBLIC FINAL io.opentelemetry.exporter.zipkin.ZipkinSpanExporterBuilder  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.exporter.zipkin.ZipkinSpanExporterBuilder setReadTimeout(long, java.util.concurrent.TimeUnit)
+	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.exporter.zipkin.ZipkinSpanExporterBuilder setReadTimeout(java.time.Duration)

docs/apidiffs/1.2.0_vs_1.1.0/opentelemetry-extension-annotations.txt

@@ -0,0 +1,2 @@
+Comparing source compatibility of  against 
+No changes.

docs/apidiffs/1.2.0_vs_1.1.0/opentelemetry-extension-aws.txt

@@ -0,0 +1,2 @@
+Comparing source compatibility of  against 
+No changes.

docs/apidiffs/1.2.0_vs_1.1.0/opentelemetry-extension-kotlin.txt

@@ -0,0 +1,2 @@
+Comparing source compatibility of  against 
+No changes.

docs/apidiffs/1.2.0_vs_1.1.0/opentelemetry-extension-trace-propagators.txt

@@ -0,0 +1,2 @@
+Comparing source compatibility of  against 
+No changes.

docs/apidiffs/1.2.0_vs_1.1.0/opentelemetry-sdk-common.txt

@@ -0,0 +1,2 @@
+Comparing source compatibility of  against 
+No changes.

docs/apidiffs/1.2.0_vs_1.1.0/opentelemetry-sdk-extension-aws.txt

@@ -0,0 +1,2 @@
+Comparing source compatibility of  against 
+No changes.

docs/apidiffs/1.2.0_vs_1.1.0/opentelemetry-sdk-extension-jaeger-remote-sampler.txt

@@ -0,0 +1,2 @@
+Comparing source compatibility of  against 
+No changes.

docs/apidiffs/1.2.0_vs_1.1.0/opentelemetry-sdk-extension-resources.txt

@@ -0,0 +1,10 @@
+Comparing source compatibility of  against 
++++  NEW CLASS: PUBLIC(+) FINAL(+) io.opentelemetry.sdk.extension.resources.HostResource  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.resources.Resource get()
++++  NEW CLASS: PUBLIC(+) FINAL(+) io.opentelemetry.sdk.extension.resources.HostResourceProvider  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW CONSTRUCTOR: PUBLIC(+) HostResourceProvider()
+	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.sdk.resources.Resource createResource(io.opentelemetry.sdk.autoconfigure.ConfigProperties)

docs/apidiffs/1.2.0_vs_1.1.0/opentelemetry-sdk-testing.txt

@@ -0,0 +1,2 @@
+Comparing source compatibility of  against 
+No changes.

docs/apidiffs/1.2.0_vs_1.1.0/opentelemetry-sdk-trace.txt

@@ -0,0 +1,2 @@
+Comparing source compatibility of  against 
+No changes.

docs/apidiffs/1.2.0_vs_1.1.0/opentelemetry-sdk.txt

@@ -0,0 +1,2 @@
+Comparing source compatibility of  against 
+No changes.

docs/apidiffs/current_vs_latest/opentelemetry-api.txt

@@ -1,7 +1,2 @@
 Comparing source compatibility of  against 
-***! MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.api.trace.Span  (not serializable)
-	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
-	+++! NEW METHOD: PUBLIC(+) io.opentelemetry.api.trace.Span setAllAttributes(io.opentelemetry.api.common.Attributes)
-***! MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.api.trace.SpanBuilder  (not serializable)
-	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
-	+++! NEW METHOD: PUBLIC(+) io.opentelemetry.api.trace.SpanBuilder setAllAttributes(io.opentelemetry.api.common.Attributes)
+No changes.

docs/apidiffs/current_vs_latest/opentelemetry-exporter-zipkin.txt

@@ -1,5 +1,2 @@
 Comparing source compatibility of  against 
-***  MODIFIED CLASS: PUBLIC FINAL io.opentelemetry.exporter.zipkin.ZipkinSpanExporterBuilder  (not serializable)
-	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
-	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.exporter.zipkin.ZipkinSpanExporterBuilder setReadTimeout(long, java.util.concurrent.TimeUnit)
-	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.exporter.zipkin.ZipkinSpanExporterBuilder setReadTimeout(java.time.Duration)
+No changes.

docs/apidiffs/current_vs_latest/opentelemetry-sdk-extension-resources.txt

@@ -1,10 +1,2 @@
 Comparing source compatibility of  against 
-+++  NEW CLASS: PUBLIC(+) FINAL(+) io.opentelemetry.sdk.extension.resources.HostResource  (not serializable)
-	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
-	+++  NEW SUPERCLASS: java.lang.Object
-	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.resources.Resource get()
-+++  NEW CLASS: PUBLIC(+) FINAL(+) io.opentelemetry.sdk.extension.resources.HostResourceProvider  (not serializable)
-	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
-	+++  NEW SUPERCLASS: java.lang.Object
-	+++  NEW CONSTRUCTOR: PUBLIC(+) HostResourceProvider()
-	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.sdk.resources.Resource createResource(io.opentelemetry.sdk.autoconfigure.ConfigProperties)
+No changes.

website_docs/_index.md

@@ -54,7 +54,7 @@ versions of the various components in sync.
       <dependency>
         <groupId>io.opentelemetry</groupId>
         <artifactId>opentelemetry-bom</artifactId>
-        <version>1.1.0</version>
+        <version>1.2.0</version>
         <type>pom</type>
         <scope>import</scope>
       </dependency>
@@ -73,7 +73,7 @@ versions of the various components in sync.
 
 ```groovy
 dependencies {
-  implementation platform("io.opentelemetry:opentelemetry-bom:1.1.0")
+  implementation platform("io.opentelemetry:opentelemetry-bom:1.2.0")
   implementation('io.opentelemetry:opentelemetry-api')
 }
 ```