From e17c02fdfbd5d45b23c6c63521b2ac6069f7bbee Mon Sep 17 00:00:00 2001
From: Trask Stalnaker <trask.stalnaker@gmail.com>
Date: Tue, 25 Apr 2023 20:04:59 -0700
Subject: [PATCH] Transition plan where both old and new attributes are sent
 for a while

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

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ed69c327753..623903cc587 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -43,6 +43,9 @@ release.
   ([#3390](https://github.com/open-telemetry/opentelemetry-specification/pull/3390))
 - BREAKING: Remove `messaging.consumer.id`, make `messaging.client_id` generic
   ([#3336](https://github.com/open-telemetry/opentelemetry-specification/pull/3336))
+- Add transition plan for upcoming breaking changes to the unstable HTTP semantic
+  conventions.
+  ([#3443](https://github.com/open-telemetry/opentelemetry-specification/pull/3443))
 
 ### Compatibility
 
diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md
index 968b0575494..8c403b08553 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**
+> HTTP instrumentation 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 the latest version SHOULD:
+>
+> * start emitting the latest semantic convention attributes on HTTP metrics
+>   _in addition_ to the attributes they are already emitting,
+>   without bumping the existing major version.
+>   (note: this SHOULD NOT increase cardinality or create new timeseries)
+> * maintain (security patching at a minimum) the existing major version
+>   for at least six months after it starts emitting both sets of attributes.
+> * stop emitting both sets of attributes in the next major version (stable
+>   next major version SHOULD NOT be released prior to October 1, 2023).
+
 ## HTTP Server
 
 ### Metric: `http.server.duration`
diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md
index dba45b01b57..5dcabcf052d 100644
--- a/specification/trace/semantic_conventions/http.md
+++ b/specification/trace/semantic_conventions/http.md
@@ -27,6 +27,19 @@ and various HTTP versions like 1.1, 2 and SPDY.
 
 <!-- tocstop -->
 
+> **Warning**
+> HTTP instrumentation 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 the latest version SHOULD:
+>
+> * start emitting the latest semantic convention attributes on spans
+>   _in addition_ to the attributes they are already emitting,
+>   without bumping the existing major version.
+> * maintain (security patching at a minimum) the existing major version
+>   for at least six months after it starts emitting both sets of attributes.
+> * stop emitting both sets of attributes in the next major version (stable
+>   next major version SHOULD NOT be released prior to October 1, 2023).
+
 ## Name
 
 HTTP spans MUST follow the overall [guidelines for span names](../api.md#span).