From 696b7b5c7ce4da36d11302871ac2dc500e8fe01c Mon Sep 17 00:00:00 2001 From: Matt McCleary <43887470+mattmccleary@users.noreply.github.com> Date: Tue, 13 Feb 2024 15:13:25 -0800 Subject: [PATCH 1/9] Add Caution Note re Experimental SemConvs --- content/en/docs/languages/_index.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/content/en/docs/languages/_index.md b/content/en/docs/languages/_index.md index 2b44d21a4121..49a702ad18cb 100644 --- a/content/en/docs/languages/_index.md +++ b/content/en/docs/languages/_index.md @@ -27,6 +27,12 @@ follows: {{% telemetry-support-table " " %}} +{{% alert title="Note" color="warning" %}} Even though the API/SDK status +is stable, changes to underlying [semantic convensions][SemConv] can interrupt +your data flow. If the status of a Semantic Convension that your SDK/API +depends on is `Experimental`, it may be subject to future breaking changes. + [auto]: /docs/kubernetes/operator/automatic/ [instrumentation]: /docs/concepts/instrumentation/ [otel-op]: /docs/kubernetes/operator/ +[SemConv]: /docs/concepts/semantic-conventions/ From bd88868bf85bf6569b7d23fe932924aba377fc06 Mon Sep 17 00:00:00 2001 From: Matt McCleary <43887470+mattmccleary@users.noreply.github.com> Date: Tue, 13 Feb 2024 15:16:11 -0800 Subject: [PATCH 2/9] Fix Spelling --- content/en/docs/languages/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/languages/_index.md b/content/en/docs/languages/_index.md index 49a702ad18cb..61696fd2dca8 100644 --- a/content/en/docs/languages/_index.md +++ b/content/en/docs/languages/_index.md @@ -28,8 +28,8 @@ follows: {{% telemetry-support-table " " %}} {{% alert title="Note" color="warning" %}} Even though the API/SDK status -is stable, changes to underlying [semantic convensions][SemConv] can interrupt -your data flow. If the status of a Semantic Convension that your SDK/API +is stable, changes to underlying [semantic conventions][SemConv] can interrupt +your data flow. If the status of a Semantic Convention that your SDK/API depends on is `Experimental`, it may be subject to future breaking changes. [auto]: /docs/kubernetes/operator/automatic/ From fd740bf09a3ca852f1ac2fbfe9b2f903cae0d313 Mon Sep 17 00:00:00 2001 From: Matt McCleary <43887470+mattmccleary@users.noreply.github.com> Date: Tue, 13 Feb 2024 15:19:28 -0800 Subject: [PATCH 3/9] Minor language update --- content/en/docs/languages/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/languages/_index.md b/content/en/docs/languages/_index.md index 61696fd2dca8..9f37fb33837b 100644 --- a/content/en/docs/languages/_index.md +++ b/content/en/docs/languages/_index.md @@ -29,7 +29,7 @@ follows: {{% alert title="Note" color="warning" %}} Even though the API/SDK status is stable, changes to underlying [semantic conventions][SemConv] can interrupt -your data flow. If the status of a Semantic Convention that your SDK/API +your data flow. If the status of a Semantic Convention that your instrumentation depends on is `Experimental`, it may be subject to future breaking changes. [auto]: /docs/kubernetes/operator/automatic/ From dd8f6489b36b53814bf82a612036af63bff46229 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Tue, 13 Feb 2024 18:53:28 -0500 Subject: [PATCH 4/9] Add alert closing tag --- content/en/docs/languages/_index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/en/docs/languages/_index.md b/content/en/docs/languages/_index.md index 9f37fb33837b..0a674a079655 100644 --- a/content/en/docs/languages/_index.md +++ b/content/en/docs/languages/_index.md @@ -31,6 +31,7 @@ follows: is stable, changes to underlying [semantic conventions][SemConv] can interrupt your data flow. If the status of a Semantic Convention that your instrumentation depends on is `Experimental`, it may be subject to future breaking changes. +{{% /alert %}} [auto]: /docs/kubernetes/operator/automatic/ [instrumentation]: /docs/concepts/instrumentation/ From b1834a5557a7ffc570ef7011c4c84c6e18e21de1 Mon Sep 17 00:00:00 2001 From: opentelemetrybot <107717825+opentelemetrybot@users.noreply.github.com> Date: Wed, 14 Feb 2024 08:41:24 +0000 Subject: [PATCH 5/9] Results from /fix:format --- content/en/docs/languages/_index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/en/docs/languages/_index.md b/content/en/docs/languages/_index.md index 0a674a079655..8b5f2ec278bd 100644 --- a/content/en/docs/languages/_index.md +++ b/content/en/docs/languages/_index.md @@ -27,9 +27,9 @@ follows: {{% telemetry-support-table " " %}} -{{% alert title="Note" color="warning" %}} Even though the API/SDK status -is stable, changes to underlying [semantic conventions][SemConv] can interrupt -your data flow. If the status of a Semantic Convention that your instrumentation +{{% alert title="Note" color="warning" %}} Even though the API/SDK status is +stable, changes to underlying [semantic conventions][SemConv] can interrupt your +data flow. If the status of a Semantic Convention that your instrumentation depends on is `Experimental`, it may be subject to future breaking changes. {{% /alert %}} From 207d7b7adb06259146cc63be60c308a95f280b2a Mon Sep 17 00:00:00 2001 From: Matt McCleary <43887470+mattmccleary@users.noreply.github.com> Date: Wed, 14 Feb 2024 15:11:26 -0800 Subject: [PATCH 6/9] Link Reference Co-authored-by: Severin Neumann --- content/en/docs/languages/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/languages/_index.md b/content/en/docs/languages/_index.md index 8b5f2ec278bd..0c53313dbbb2 100644 --- a/content/en/docs/languages/_index.md +++ b/content/en/docs/languages/_index.md @@ -36,4 +36,4 @@ depends on is `Experimental`, it may be subject to future breaking changes. [auto]: /docs/kubernetes/operator/automatic/ [instrumentation]: /docs/concepts/instrumentation/ [otel-op]: /docs/kubernetes/operator/ -[SemConv]: /docs/concepts/semantic-conventions/ +[sem-conv]: /docs/concepts/semantic-conventions/ From 58d2dab458da9a1d5ef78ae207313c5b7b693289 Mon Sep 17 00:00:00 2001 From: Matt McCleary <43887470+mattmccleary@users.noreply.github.com> Date: Wed, 14 Feb 2024 15:12:37 -0800 Subject: [PATCH 7/9] Update Link Reference Co-authored-by: Severin Neumann --- content/en/docs/languages/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/languages/_index.md b/content/en/docs/languages/_index.md index 0c53313dbbb2..02ae22fda01f 100644 --- a/content/en/docs/languages/_index.md +++ b/content/en/docs/languages/_index.md @@ -28,7 +28,7 @@ follows: {{% telemetry-support-table " " %}} {{% alert title="Note" color="warning" %}} Even though the API/SDK status is -stable, changes to underlying [semantic conventions][SemConv] can interrupt your +stable, changes to underlying [semantic conventions][sem-conv] can interrupt your data flow. If the status of a Semantic Convention that your instrumentation depends on is `Experimental`, it may be subject to future breaking changes. {{% /alert %}} From c21a5f74345a1a7762cdcfd45cdc706f43dac2a4 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 15 Feb 2024 12:05:50 -0500 Subject: [PATCH 8/9] Rework and reposition the alert --- content/en/docs/languages/_index.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/content/en/docs/languages/_index.md b/content/en/docs/languages/_index.md index 02ae22fda01f..8d7d3f5bd74c 100644 --- a/content/en/docs/languages/_index.md +++ b/content/en/docs/languages/_index.md @@ -25,15 +25,19 @@ Java, Node.js, Python, Go into your application. The current status of the major functional components for OpenTelemetry is as follows: -{{% telemetry-support-table " " %}} +{{% alert title="Warning" color="warning" %}} + +Even though an API/SDK status is stable, changes to underlying [semantic +conventions] can interrupt your data flow. If the status of a semantic +convention that your instrumentation depends on is `Experimental`, it may be +subject to future breaking changes. + +[semantic conventions]: /docs/concepts/semantic-conventions/ -{{% alert title="Note" color="warning" %}} Even though the API/SDK status is -stable, changes to underlying [semantic conventions][sem-conv] can interrupt your -data flow. If the status of a Semantic Convention that your instrumentation -depends on is `Experimental`, it may be subject to future breaking changes. {{% /alert %}} +{{% telemetry-support-table " " %}} + [auto]: /docs/kubernetes/operator/automatic/ [instrumentation]: /docs/concepts/instrumentation/ [otel-op]: /docs/kubernetes/operator/ -[sem-conv]: /docs/concepts/semantic-conventions/ From ab5dc00c0fe71e5b54615afe48e7b3f449fc2fd9 Mon Sep 17 00:00:00 2001 From: Matt McCleary <43887470+mattmccleary@users.noreply.github.com> Date: Fri, 16 Feb 2024 12:58:41 -0800 Subject: [PATCH 9/9] Improve Wording of Caution Note Co-authored-by: Patrice Chalin --- content/en/docs/languages/_index.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/content/en/docs/languages/_index.md b/content/en/docs/languages/_index.md index 8d7d3f5bd74c..f1ae703374f6 100644 --- a/content/en/docs/languages/_index.md +++ b/content/en/docs/languages/_index.md @@ -25,14 +25,15 @@ Java, Node.js, Python, Go into your application. The current status of the major functional components for OpenTelemetry is as follows: -{{% alert title="Warning" color="warning" %}} +{{% alert title="Important" color="warning" %}} -Even though an API/SDK status is stable, changes to underlying [semantic -conventions] can interrupt your data flow. If the status of a semantic -convention that your instrumentation depends on is `Experimental`, it may be -subject to future breaking changes. +Regardless of an API/SDK's status, if your instrumentation relies on [semantic +conventions] that are marked as [Experimental] in the [semantic conventions +specification], your data flow might be subject to **breaking changes**. [semantic conventions]: /docs/concepts/semantic-conventions/ +[Experimental]: /docs/specs/otel/document-status/ +[semantic conventions specification]: /docs/specs/semconv/ {{% /alert %}}