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

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

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4921c3137ad..acd09b0e73c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,6 +25,10 @@ release.
 
 ### Semantic Conventions
 
+- Add transition plan for upcoming breaking changes to the unstable HTTP semantic
+  conventions.
+  ([#3381](https://github.com/open-telemetry/opentelemetry-specification/pull/3381))
+
 ### Compatibility
 
 ### OpenTelemetry Protocol
diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md
index e18bb475bae..1598fde4e75 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 SHOULD NOT emit HTTP semantic conventions later than
+> [v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md)
+> until October 1, 2023 (an opt-in flag to emit the latest HTTP semantic conventions
+> during this time is ok).
+>
+> After October 1, 2023, HTTP instrumentation published from
+> [OpenTelemetry repositories](https://github.com/orgs/open-telemetry/repositories)
+> which adopt the latest HTTP semantic conventions SHOULD provide 3-months of overlap where
+> they support both the old (1.20.0 or earlier) and the latest HTTP semantic conventions.
+> This support can be provided by a configuration option on the latest instrumentation version
+> to opt-in (revert) to the old conventions, or it can be provided by patching old
+> instrumentation versions for security-related issues during this overlap.
+
 ## HTTP Server
 
 ### Metric: `http.server.duration`
diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md
index 636683beeb0..18f1f5bf8bd 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**
+> HTTP instrumentation SHOULD NOT emit HTTP semantic conventions later than
+> [v1.20.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/trace/semantic_conventions/http.md)
+> until October 1, 2023 (an opt-in flag to emit the latest HTTP semantic conventions
+> during this time is ok).
+> 
+> After October 1, 2023, HTTP instrumentation published from
+> [OpenTelemetry repositories](https://github.com/orgs/open-telemetry/repositories)
+> which adopt the latest HTTP semantic conventions SHOULD provide 3-months of overlap where
+> they support both the old (1.20.0 or earlier) and the latest HTTP semantic conventions.
+> This support can be provided by a configuration option on the latest instrumentation version
+> to opt-in (revert) to the old conventions, or it can be provided by patching old
+> instrumentation versions for security-related issues during this overlap. 
+
 ## Name
 
 HTTP spans MUST follow the overall [guidelines for span names](../api.md#span).