Enhance adjust-pages patch logic to target only one version; add patches

scripts/content-modules/adjust-pages.pl

@@ -75,37 +75,96 @@ ()
   print "---\n";
 }
 
+sub getVersFromGitmodules($) {
+  # Returns the pinned version of the submodule $specName from .gitmodules, or undef if not found.
+  my ($specName) = @_;
+  my $pinKey = "$specName-pin";
+
+  open(my $fh, '<', '.gitmodules') or return undef;
+  my $vers;
+
+  while (my $line = <$fh>) {
+    if ($line =~ /^\s*$pinKey\s*=\s*(.+)/) {
+      $vers = $1;
+      chomp($vers);
+      $vers =~ s/^v//;  # Remove leading v
+      last;
+    }
+  }
+  close($fh);
+  return $vers;
+}
+
 sub applyPatchOrPrintMsgIf($$$) {
   # Returns truthy if patch should be applied, otherwise prints message (once) as to why not.
+  # The patch is applied if $submoduleVers starts with $targetVers.
 
   my ($patchID, $specName, $targetVers) = @_;
-  my $vers;
+  my $vers = $versions{$specName};
+  my $submoduleVers = getVersFromGitmodules($specName);
   my $key = $specName . $patchID;
 
-  return 0 if $patchMsgCount{$key};
-
-  if (($vers = $versions{$specName}) gt $targetVers) {
-    print STDOUT "INFO: remove obsolete patch '$patchID' now that spec '$specName' is at v$vers > v$targetVers - $0\n";
-  } elsif (($vers = $versFromSubmod{$specName}) gt $targetVers) {
-    print STDOUT "INFO [$patchID]: skipping patch '$patchID' since spec '$specName' submodule is at v$vers > v$targetVers - $0\n";
+  return 0 if $patchMsgCount{$key} && $patchMsgCount{$key} ne 'Apply the patch';
+
+  if ($submoduleVers && $submoduleVers =~ /^$targetVers/) {
+    print STDOUT "INFO: $0: applying patch '$patchID' since spec '$specName' " .
+      "submodule is at version '$submoduleVers', and it starts with the patch target '$targetVers'" .
+      "\n" unless $patchMsgCount{$key};
+    return $patchMsgCount{$key} = 'Apply the patch';
+  } elsif ($vers ge $targetVers) {
+    print STDOUT "INFO: $0: patch '$patchID' is probably obsolete now that " .
+      "spec '$specName' is at version '$vers' >= '$targetVers' (patch target version); " .
+      "if so, remove the patch\n";
   } else {
-    return 'Apply the patch';
+    print STDOUT "INFO: $0: skipping patch '$patchID' since spec '$specName' " .
+      "submodule is at version '$vers' < '$targetVers' (patch target version); " .
+      "and submodule version '$submoduleVers' doesn't start with the patch target '$targetVers'\n";
   }
   $patchMsgCount{$key}++;
   return 0;
 }
 
+# =================================================================================
+# KEEP THE FOLLOWING AS A TEMPLATE; copy it and modify it as needed.
+# =================================================================================
+sub patchSpec_because_of_SemConv_DockerAPIVersions_AsTemplate() {
+  return unless
+    # Restrict the patch to the proper spec, and section or file:
+    $ARGV =~ m|^tmp/semconv/docs/|
+    &&
+    # Call helper function that will cause the function to return early if the
+    # patch should not be applied. The patch is applied if the submodule version
+    # (from .gitmodules) starts with the target version (arg 3). The first
+    # argument is a unique id that will be printed if the patch is outdated.
+    # Otherwise, if the patch is still relevant we fall through to the body of
+    # this patch function.
+    #
+    # Specify the target version as, e.g., '1.38.0', or to apply only to dev
+    # versions, use '1.38.0-' with a trailing hyphen.
+    applyPatchOrPrintMsgIf('2025-11-21-docker-api-versions', 'semconv', '1.38.0');
+
+  # Give infor about the patch:
+  #
+  # For the problematic links, see:
+  # https://github.com/open-telemetry/semantic-conventions/issues/3103
+  #
+  # Replace older Docker API versions with the latest one like in:
+  # https://github.com/open-telemetry/semantic-conventions/pull/3093
+
+  # This is the actual regex-based patch code:
+  s{
+    (https://docs.docker.com/reference/api/engine/version)/v1.(43|51)/(\#tag/)
+  }{$1/v1.52/$3}gx;
+}
+
 sub patchSpec_because_of_SemConv_DockerAPIVersions() {
   return unless
     # Restrict the patch to the proper spec, and section or file:
     $ARGV =~ m|^tmp/semconv/docs/|
     &&
     # Call helper function that will cause the function to return early if the
-    # current version of the named spec (arg 2) is greater than the target
-    # version (arg 3). The first argument is a unique id that will be printed if
-    # the patch is outdated. Otherwise, if the patch is still relevant we fall
-    # through to the body of this patch function.
-    applyPatchOrPrintMsgIf('2025-11-21-docker-api-versions', 'semconv', '1.39.0-dev');
+    # patch should not be applied. See patch template above for details.
+    applyPatchOrPrintMsgIf('2025-11-21-docker-api-versions', 'semconv', '1.38.0');
 
   # Give infor about the patch:
   #
@@ -121,6 +180,19 @@ ()
   }{$1/v1.52/$3}gx;
 }
 
+sub patchSpec_because_of_SemConv_DatabaseRenamedToDb() {
+  return unless
+    # Restrict the patch to the proper spec, and section or file:
+    # Note that here we replace links into semconv from the spec
+    $ARGV =~ m|^tmp/otel/specification/|
+      && applyPatchOrPrintMsgIf('2025-11-26-database-section-renamed-to-db', 'semconv', '1.38.0-');
+
+  # Give infor about the patch, see:
+  # https://github.com/open-telemetry/opentelemetry.io/pull/8311#issue-3577941378
+
+  s|(/semconv)/database(/database-)|$1/db$2|g;
+}
+
 sub getVersFromSubmodule() {
   my %repoNames = qw(
     otlp    opentelemetry-proto
@@ -244,6 +316,8 @@ ()
     )
   }{$otelSpecRepoUrl/tree/v$otelSpecVers/$2}gx;
 
+  patchSpec_because_of_SemConv_DatabaseRenamedToDb();
+
   s|\.\./((?:examples/)?README\.md)|$otlpSpecRepoUrl/tree/v$otlpSpecVers/$1|g if $ARGV =~ /^tmp\/otlp/;
 
   # Make website-local page references local: