Fix spec link update to update older versions too (#3526)

trask · web-flow · commit bd036609f92d · 2026-03-10T20:13:15.000Z
diff --git a/.github/scripts/update-spec-repo-links.sh b/.github/scripts/update-spec-repo-links.sh
@@ -4,9 +4,6 @@
 #
 # ./internal/tools/update-spec-repo-links.sh v1.41.0
 
-# this version should be kept up-to-date with the spec version that links use
-PREVIOUS_SPECIFICATION_VERSION=v1.55.0
-
 # Set this to the version number you want to KEEP in URLs in the repository.
 LATEST_SPECIFICATION_VERSION=$1
 # The specific pattern we look for when replacing URLs
@@ -15,14 +12,17 @@ SPECIFICATION_URL_PREFIX="https://github.com/open-telemetry/opentelemetry-specif
 SPECIFICATION_BADGE_PREFIX="https://img.shields.io/badge/OTel_specification_version-"
 SPECIFICATION_BADGE_RELEASE_TAG_PREFIX="https://github.com/open-telemetry/opentelemetry-specification/releases/tag/"
 
-
 fix_file() {
-  echo Fixing file $1
-  sed -i \
-   -e "s,${SPECIFICATION_URL_PREFIX}${PREVIOUS_SPECIFICATION_VERSION},${SPECIFICATION_URL_PREFIX}${LATEST_SPECIFICATION_VERSION},g" \
-   -e "s,${SPECIFICATION_BADGE_PREFIX}${PREVIOUS_SPECIFICATION_VERSION},${SPECIFICATION_BADGE_PREFIX}${LATEST_SPECIFICATION_VERSION},g" \
-   -e "s,${SPECIFICATION_BADGE_RELEASE_TAG_PREFIX}${PREVIOUS_SPECIFICATION_VERSION},${SPECIFICATION_BADGE_RELEASE_TAG_PREFIX}${LATEST_SPECIFICATION_VERSION},g" \
-   "$1"
+  echo Fixing file "$1"
+
+  # Replace any versioned spec URL/badge with the latest version.
+  # Uses a negative lookahead to skip URLs pointing to semantic_conventions/
+  # paths that were moved from the spec repo and no longer exist in newer versions.
+  perl -pi -e "
+    s,\Q${SPECIFICATION_URL_PREFIX}\Ev1\.\d+\.\d+(?=/specification/(?!.*/semantic_conventions/)),${SPECIFICATION_URL_PREFIX}${LATEST_SPECIFICATION_VERSION},g;
+    s,\Q${SPECIFICATION_BADGE_PREFIX}\Ev1\.\d+\.\d+,${SPECIFICATION_BADGE_PREFIX}${LATEST_SPECIFICATION_VERSION},g;
+    s,\Q${SPECIFICATION_BADGE_RELEASE_TAG_PREFIX}\Ev1\.\d+\.\d+,${SPECIFICATION_BADGE_RELEASE_TAG_PREFIX}${LATEST_SPECIFICATION_VERSION},g;
+  " "$1"
 }
 
 important_files=("docs" "model" "README.md")
diff --git a/.github/workflows/auto-update-spec-repo-links.yml b/.github/workflows/auto-update-spec-repo-links.yml
@@ -13,7 +13,6 @@ jobs:
     runs-on: ubuntu-latest
     if: github.repository_owner == 'open-telemetry'
     outputs:
-      current-version: ${{ steps.check-versions.outputs.current-version }}
       latest-version: ${{ steps.check-versions.outputs.latest-version }}
       already-opened: ${{ steps.check-versions.outputs.already-opened }}
     steps:
@@ -24,9 +23,6 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          current_version=$(grep "PREVIOUS_SPECIFICATION_VERSION=v.*" \
-                                 .github/scripts/update-spec-repo-links.sh \
-                            | sed "s/PREVIOUS_SPECIFICATION_VERSION=//")
           latest_version=$(gh release view \
                                --repo open-telemetry/opentelemetry-specification \
                                --json tagName \
@@ -41,7 +37,6 @@ jobs:
             already_opened=true
           fi
 
-          echo "current-version=$current_version" >> $GITHUB_OUTPUT
           echo "latest-version=$latest_version" >> $GITHUB_OUTPUT
           echo "already-opened=$already_opened" >> $GITHUB_OUTPUT
 
@@ -50,7 +45,6 @@ jobs:
       contents: write # required for pushing changes
     runs-on: ubuntu-latest
     if: |
-      needs.check-versions.outputs.current-version != needs.check-versions.outputs.latest-version &&
       needs.check-versions.outputs.already-opened != 'true'
     needs:
       - check-versions
@@ -63,9 +57,7 @@ jobs:
       - name: Update version
         env:
           VERSION: ${{ needs.check-versions.outputs.latest-version }}
-        run: |
-          .github/scripts/update-spec-repo-links.sh $VERSION
-          sed -i "s/^PREVIOUS_SPECIFICATION_VERSION=.*/PREVIOUS_SPECIFICATION_VERSION=$VERSION/" .github/scripts/update-spec-repo-links.sh
+        run: .github/scripts/update-spec-repo-links.sh $VERSION
 
       - uses: actions/create-github-app-token@29824e69f54612133e76f7eaac726eef6c875baf # v2.2.1
         id: otelbot-token
diff --git a/docs/cicd/cicd-spans.md b/docs/cicd/cicd-spans.md
@@ -35,7 +35,7 @@ This span describes a CICD pipeline run.
 
 For all pipeline runs, a span with kind `SERVER` SHOULD be created corresponding to the execution of the pipeline run.
 
-**Span name** MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.43.0/specification/trace/api.md#span).
+**Span name** MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.55.0/specification/trace/api.md#span).
 
 The span name SHOULD be `{action} {pipeline}` if there is a (low-cardinality) pipeline name available.
 If the pipeline name is not available or is likely to have high cardinality, then the span name SHOULD be `{action}`.
diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md
@@ -57,7 +57,7 @@ This span represents a client call to Generative AI model or service that genera
 
 **Span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}`.
 Semantic conventions for individual GenAI systems and frameworks MAY specify different span name format
-and MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.37.0/specification/trace/api.md#span).
+and MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.55.0/specification/trace/api.md#span).
 
 **Span kind** SHOULD be `CLIENT` and MAY be set to `INTERNAL` on spans representing
 call to models running in the same process. It's RECOMMENDED to use `CLIENT` kind
diff --git a/docs/gen-ai/mcp.md b/docs/gen-ai/mcp.md
@@ -469,7 +469,7 @@ It SHOULD be set to `pipe` if the transport is stdio.
 This metric is [recommended][MetricRecommended].
 
 This metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.55.0/specification/metrics/api.md#instrument-advisory-parameters)
 of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`.
 
 <!-- semconv metric.mcp.client.operation.duration -->
@@ -606,7 +606,7 @@ It SHOULD be set to `pipe` if the transport is stdio.
 This metric is [recommended][MetricRecommended].
 
 This metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.55.0/specification/metrics/api.md#instrument-advisory-parameters)
 of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`.
 
 <!-- semconv metric.mcp.server.operation.duration -->
@@ -737,7 +737,7 @@ It SHOULD be set to `pipe` if the transport is stdio.
 This metric is [recommended][MetricRecommended].
 
 This metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.55.0/specification/metrics/api.md#instrument-advisory-parameters)
 of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`.
 
 <!-- semconv metric.mcp.client.session.duration -->
@@ -820,7 +820,7 @@ is HTTP. It SHOULD be set to `pipe` if the transport is stdio.
 This metric is [recommended][MetricRecommended].
 
 This metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.55.0/specification/metrics/api.md#instrument-advisory-parameters)
 of `[ 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 30, 60, 120, 300 ]`.
 
 <!-- semconv metric.mcp.server.session.duration -->
diff --git a/docs/how-to-write-conventions/resource-and-entities.md b/docs/how-to-write-conventions/resource-and-entities.md
@@ -177,7 +177,7 @@ minimal set of attributes that is sufficient for uniquely identifying that entit
 uniquely identified by (`process.pid`,`process.creation.time`)
 attributes. Adding for example `process.executable.name`
 attribute to the identity is unnecessary and violates the
-rule of having a [minimally sufficient ID](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.45.0/specification/entities/data-model.md#minimally-sufficient-identity).
+rule of having a [minimally sufficient ID](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.55.0/specification/entities/data-model.md#minimally-sufficient-identity).
 
 Identifying attributes generally form the lifespan of an entity. This is
 important, particularly, for metrics written against an entity. The lifespan
@@ -232,7 +232,7 @@ semantic convention namespacing rules.
 ## Background: Resource and Entities
 
 In OpenTelemetry, every signal is associated with a Resource.
-According to the [Specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.45.0/specification/resource/README.md#overview)
+According to the [Specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.55.0/specification/resource/README.md#overview)
 this is:
 
 > A Resource is a representation of the entity producing telemetry. Within
@@ -247,7 +247,7 @@ this is:
 > * It SHOULD allow users to determine where that entity resides within their
 >   infrastructure.
 
-All resources are composed of [Entities](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.45.0/specification/entities/README.md#overview).
+All resources are composed of [Entities](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.55.0/specification/entities/README.md#overview).
 An entity is specified as:
 
 > Entity represents an object of interest associated with
@@ -262,7 +262,7 @@ several key differences between the two:
   *descriptive* attributes.
   - Identifying attributes can be used to identify the entity
     within some system (See
-    [minimally sufficient id](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.45.0/specification/entities/data-model.md#minimally-sufficient-identity)).
+    [minimally sufficient id](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.55.0/specification/entities/data-model.md#minimally-sufficient-identity)).
     For Example, the `k8s.pod.uid` would be considered an
     identifying attribute for a pod within kubernetes.
   - *Descriptive* attributes can be used to provide additional labels for
diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md
@@ -55,7 +55,7 @@ metrics can be filtered for finer grain analysis.
 This metric is [required][MetricRequired].
 
 This metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.55.0/specification/metrics/api.md#instrument-advisory-parameters)
 of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
 
 <!-- semconv metric.rpc.server.call.duration -->
@@ -154,7 +154,7 @@ Semantic conventions for individual RPC frameworks SHOULD document what `rpc.res
 This metric is [required][MetricRequired].
 
 This metric SHOULD be specified with
-[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/metrics/api.md#instrument-advisory-parameters)
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.55.0/specification/metrics/api.md#instrument-advisory-parameters)
 of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`.
 
 <!-- semconv metric.rpc.client.call.duration -->
diff --git a/docs/runtime/cpython-metrics.md b/docs/runtime/cpython-metrics.md
@@ -128,5 +128,5 @@ This metric is [recommended][MetricRecommended].
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
-[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.42.0/specification/document-status.md
+[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.55.0/specification/document-status.md
 [MetricRecommended]: /docs/general/metric-requirement-level.md#recommended
diff --git a/model/cicd/spans.yaml b/model/cicd/spans.yaml
@@ -6,7 +6,7 @@ groups:
     note: |
       For all pipeline runs, a span with kind `SERVER` SHOULD be created corresponding to the execution of the pipeline run.
 
-      **Span name** MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.43.0/specification/trace/api.md#span).
+      **Span name** MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.55.0/specification/trace/api.md#span).
 
       The span name SHOULD be `{action} {pipeline}` if there is a (low-cardinality) pipeline name available.
       If the pipeline name is not available or is likely to have high cardinality, then the span name SHOULD be `{action}`.
diff --git a/model/gen-ai/spans.yaml b/model/gen-ai/spans.yaml
@@ -111,7 +111,7 @@ groups:
     note: |
       **Span name** SHOULD be `{gen_ai.operation.name} {gen_ai.request.model}`.
       Semantic conventions for individual GenAI systems and frameworks MAY specify different span name format
-      and MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.37.0/specification/trace/api.md#span).
+      and MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.55.0/specification/trace/api.md#span).
 
       **Span kind** SHOULD be `CLIENT` and MAY be set to `INTERNAL` on spans representing
       call to models running in the same process. It's RECOMMENDED to use `CLIENT` kind
