Merge branch 'main' into 1600-cicd-metrics

christophe-kamphaus-jemmic · Jan 20, 2025 · 1ce47a9 · 1ce47a9
2 parents 02e044a + b810141
commit 1ce47a9
Show file tree

Hide file tree

Showing 5 changed files with 35 additions and 29 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -35,7 +35,6 @@ requirements and recommendations.
   - [Update the tables of content](#update-the-tables-of-content)
   - [Markdown link check](#markdown-link-check)
 - [Updating the referenced specification version](#updating-the-referenced-specification-version)
-- [Making a Release](#making-a-release)
 - [Merging existing ECS conventions](#merging-existing-ecs-conventions)
 
 <!-- tocstop -->
@@ -415,33 +414,6 @@ make markdown-link-check
 4. Run the script from the root directory, e.g. `semantic-conventions$ ./internal/tools/update_specification_version.sh`.
 5. Add all modified files to the change submit and submit a PR.
 
-## Making a Release
-
-- Ensure the referenced specification version is up to date. Use
-  [tooling to update the spec](#updating-the-referenced-specification-version)
-  if needed.
-- Run [opentelemetry.io workflow](https://github.com/open-telemetry/opentelemetry.io/actions/workflows/build-dev.yml)
-  against `semantic-conventions` submodule as a smoke-test for docs. Fix broken links, if any.
-- Create a staging branch for the release.
-  - Update `schema-next.yaml` file and move to `schemas/{version}`
-    - Ensure the `next` version is appropriately configured as the `{version}`.
-    - Copy `schema-next.yaml` to `schemas/{version}`.
-    - Add `next` as a version in `schema-next.yaml` version.
-  - Run `make chlog-update VERSION=v{version}`
-    - `make chlog-update` will clean up all the current `.yaml` files inside the
-      `.chloggen` folder automatically
-    - Double check that `CHANGELOG.md` is updated with the proper `v{version}`
-  - Send staging branch as PR for review.
-- After the release PR is merged, create a [new release](https://github.com/open-telemetry/semantic-conventions/releases/new):
-  - Set title and tag to `v{version}`
-  - Set target to the commit of the merged release PR
-  - Copy changelog to the release notes
-  - Verify that the release looks like expected
-  - Publish release
-
-New release is then auto-discovered by [opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io) pipelines which (via bot-generated PR)
-eventually results in new version of schema file being published.
-
 ## Merging existing ECS conventions
 
 The Elastic Common Schema (ECS) is being merged into OpenTelemetry Semantic

diff --git a/RELEASING.md b/RELEASING.md
@@ -0,0 +1,26 @@
+# Making a Release
+
+- Ensure the referenced specification version is up to date. Use
+  [tooling to update the spec](./CONTRIBUTING.md#updating-the-referenced-specification-version)
+  if needed.
+- Run [opentelemetry.io workflow](https://github.com/open-telemetry/opentelemetry.io/actions/workflows/build-dev.yml)
+  against `semantic-conventions` submodule as a smoke-test for docs. Fix broken links, if any.
+- Create a staging branch for the release.
+  - Update `schema-next.yaml` file and move to `schemas/{version}`
+    - Ensure the `next` version is appropriately configured as the `{version}`.
+    - Copy `schema-next.yaml` to `schemas/{version}`.
+    - Add `next` as a version in `schema-next.yaml` version.
+  - Run `make chlog-update VERSION=v{version}`
+    - `make chlog-update` will clean up all the current `.yaml` files inside the
+      `.chloggen` folder automatically
+    - Double check that `CHANGELOG.md` is updated with the proper `v{version}`
+  - Send staging branch as PR for review.
+- After the release PR is merged, create a [new release](https://github.com/open-telemetry/semantic-conventions/releases/new):
+  - Set title and tag to `v{version}`
+  - Set target to the commit of the merged release PR
+  - Copy changelog to the release notes
+  - Verify that the release looks like expected
+  - Publish release
+
+New release is then auto-discovered by [opentelemetry.io](https://github.com/open-telemetry/opentelemetry.io) pipelines which (via bot-generated PR)
+eventually results in new version of schema file being published.
diff --git a/docs/general/recording-errors.md b/docs/general/recording-errors.md
@@ -61,7 +61,7 @@ When the operation ends with an error, instrumentation:
   When the operation fails with an exception, the span status description SHOULD be set to
   the exception message.
 
-Refer to the [recording exceptions](#recording-errors) on capturing exception
+Refer to the [recording exceptions](#recording-exceptions) on capturing exception
 details.
 
 ## Recording errors on metrics

diff --git a/docs/non-normative/db-migration.md b/docs/non-normative/db-migration.md
@@ -22,6 +22,10 @@ updated to the stable database semantic conventions, they:
 - May drop the environment variable in their next major version and emit only
   the stable database conventions.
 
+> [!NOTE]
+> `OTEL_SEMCONV_STABILITY_OPT_IN` is only intended to be used when migrating
+> from an experimental semantic convention to its initial stable version.
+
 ## Summary of changes
 
 This section summarizes the changes made to the HTTP semantic conventions

diff --git a/docs/non-normative/http-migration.md b/docs/non-normative/http-migration.md
@@ -29,6 +29,10 @@ updated to the stable HTTP semantic conventions, they:
 - May drop the environment variable in their next major version and emit only
   the stable HTTP and networking conventions.
 
+> [!NOTE]
+> `OTEL_SEMCONV_STABILITY_OPT_IN` is only intended to be used when migrating
+> from an experimental semantic convention to its initial stable version.
+
 ## Summary of changes
 
 This section summarizes the changes made to the HTTP semantic conventions