From 34d23d50825d0d46f8731a9c8a0eca3581f93dd1 Mon Sep 17 00:00:00 2001
From: Trask Stalnaker <trask.stalnaker@gmail.com>
Date: Mon, 17 Apr 2023 09:41:51 -0700
Subject: [PATCH] Add transition plan for upcoming breaking changes to the
 unstable HTTP semantic conventions

---
 CHANGELOG.md                                       |  3 +++
 .../metrics/semantic_conventions/http-metrics.md   | 14 ++++++++++++++
 specification/trace/semantic_conventions/http.md   | 14 ++++++++++++++
 3 files changed, 31 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 52188613a7c..b7f6efffb3e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -41,6 +41,9 @@ release.
   ([#3388](https://github.com/open-telemetry/opentelemetry-specification/pull/3388))
 - Change http.server.duration and http.client.duration units to seconds
   ([#3390](https://github.com/open-telemetry/opentelemetry-specification/pull/3390))
+- Add transition plan for upcoming breaking changes to the unstable HTTP semantic
+  conventions.
+  ([#3404](https://github.com/open-telemetry/opentelemetry-specification/pull/3404))
 
 ### Compatibility
 
diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md
index 968b0575494..8162786e030 100644
--- a/specification/metrics/semantic_conventions/http-metrics.md
+++ b/specification/metrics/semantic_conventions/http-metrics.md
@@ -26,6 +26,20 @@ operations. By adding HTTP attributes to metric events it allows for finely tune
 
 <!-- tocstop -->
 
+> **Warning**
+> v1.21.0 of this document will introduce significant breaking changes to the (not yet stable)
+> HTTP semantic conventions.
+>
+> HTTP instrumentations updating from
+> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md) 
+> (or prior) to this new version SHOULD bump their major version
+> even though the instrumentation has not been declared stable.
+> And the previous major version SHOULD be supported until February 1, 2023
+> (e.g. at least security patches).
+> 
+> This major version bump will signal that users should take care when upgrading the
+> instrumentation, including verifying whether their backend supports the new major version.
+
 ## HTTP Server
 
 ### Metric: `http.server.duration`
diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md
index dba45b01b57..f1aa105045c 100644
--- a/specification/trace/semantic_conventions/http.md
+++ b/specification/trace/semantic_conventions/http.md
@@ -27,6 +27,20 @@ and various HTTP versions like 1.1, 2 and SPDY.
 
 <!-- tocstop -->
 
+> **Warning**
+> v1.21.0 of this document will introduce significant breaking changes to the (not yet stable)
+> HTTP semantic conventions.
+>
+> HTTP instrumentations updating from
+> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md)
+> (or prior) to this new version SHOULD bump their major version
+> even though the instrumentation has not been declared stable.
+> And the previous major version SHOULD be supported until February 1, 2023
+> (e.g. at least security patches).
+>
+> This major version bump will signal that users should take care when upgrading the
+> instrumentation, including verifying whether their backend supports the new major version.
+
 ## Name
 
 HTTP spans MUST follow the overall [guidelines for span names](../api.md#span).