Merge pull request #19452 from dvdksn/version-callouts

feat: version callouts

content/build/building/variables.md

@@ -343,7 +343,7 @@ Setting `NO_COLOR` to anything turns off colorized output, as recommended by
 
 ### BUILDKIT_HOST
 
-_Introduced in [Buildx v0.9.0](../release-notes.md#090)_
+{{< introduced buildx 0.9.0 "../release-notes.md#090" >}}
 
 You use the `BUILDKIT_HOST` to specify the address of a BuildKit daemon to use
 as a remote builder. This is the same as specifying the address as a positional
@@ -465,7 +465,7 @@ $ export BUILDX_EXPERIMENTAL=1
 
 ### BUILDX_GIT_CHECK_DIRTY
 
-_Introduced in [Buildx v0.10.4](../release-notes.md#0104)_
+{{< introduced buildx 0.10.4 "../release-notes.md#0104" >}}
 
 When set to true, checks for dirty state in source control information for
 [provenance attestations](../attestations/slsa-provenance.md).
@@ -478,7 +478,7 @@ $ export BUILDX_GIT_CHECK_DIRTY=1
 
 ### BUILDX_GIT_INFO
 
-_Introduced in [Buildx v0.10.0](../release-notes.md#0100)_
+{{< introduced buildx 0.10.0 "../release-notes.md#0100" >}}
 
 When set to false, removes source control information from
 [provenance attestations](../attestations/slsa-provenance.md).
@@ -491,7 +491,7 @@ $ export BUILDX_GIT_INFO=0
 
 ### BUILDX_GIT_LABELS
 
-_Introduced in [Buildx v0.10.0](../release-notes.md#0100)_
+{{< introduced buildx 0.10.0 "../release-notes.md#0100" >}}
 
 Adds provenance labels, based on Git information, to images that you build. The
 labels are:
@@ -520,7 +520,7 @@ If the repository is in a dirty state, the `revision` gets a `-dirty` suffix.
 
 ### BUILDX_NO_DEFAULT_ATTESTATIONS
 
-_Introduced in [Buildx v0.10.4](../release-notes.md#0104)_
+{{< introduced buildx 0.10.4 "../release-notes.md#0104" >}}
 
 By default, BuildKit v0.11 and later adds
 [provenance attestations](../attestations/slsa-provenance.md) to images you

hugo.yaml

@@ -103,8 +103,14 @@ params:
   example_alpine_version: "3.19"
   example_node_version: "20"
 
-  min_api_threshold: 1.41
-
+  min_version_thresholds:
+    buildx: "0.10.0"
+    buildkit: "0.11.0"
+    engine: "24.0.0"
+    api: "1.41"
+    desktop: "4.20.0"
+    compose: "2.20.0"
+    scout: "1.0.0"
 
 menus:
   main:

i18n/en.yaml

@@ -25,3 +25,20 @@ apiPropReq:
   other: Required
 apiPropDesc:
   other: Description
+
+## component names
+
+buildx:
+  other: Buildx
+buildkit:
+  other: BuildKit
+engine:
+  other: Docker Engine
+api:
+  other: Engine API
+desktop:
+  other: Docker Desktop
+compose:
+  other: Docker Compose
+scout:
+  other: Docker Scout

layouts/shortcodes/introduced.html

@@ -0,0 +1,59 @@
+{{- /*
+Renders a version callout for when a feature was introduced in a component.
+
+Accepts positional parameters.
+Depends on site.Params.min_version_thresholds and i18n strings for component IDs
+
+@param {string} component The ID of the component as defined in site config.
+@param {string} version The version of the component in which the thing was introduced.
+@param {string} [link] A relevant link to e.g. release note.
+
+@returns {template.HTML}
+
+@examples
+
+  {{< introduced buildx 0.12.0 "../release-notes.md#0120" >}}
+
+  {{< introduced desktop "4.28" "https://example.com/" >}}
+
+*/ -}}
+
+{{- $component := .Get 0 }}
+{{- $v := .Get 1 }}
+{{- $link := .Get 2 }}
+{{- $pos := .Position }}
+{{- with (index site.Params.min_version_thresholds $component) }}
+  {{- /*
+  Hacky semver comparison.
+
+  - Split the input version and threshold version strings 
+  - Range over the input version []string
+  - Cast to ints and compare input with same index threshold []string
+  - Set threshold false if input is lower than config, and break
+  */ -}}
+  {{ $vslice := strings.Split $v "." }}
+  {{ $tslice := strings.Split . "." }}
+  {{ $versionAboveThreshold := true }}
+  {{ range $i, $e := $vslice }}
+    {{ if compare.Lt (cast.ToInt $e) (cast.ToInt (index $tslice $i)) }}
+      {{ $versionAboveThreshold = false }}
+      {{ break }}
+    {{ end }}
+  {{ end }}
+  {{- if $versionAboveThreshold }}
+  <div class="text-gray-light dark:text-gray-dark flex items-center gap-2">
+     <span class="icon-svg flex items-center">{{ partial "icon.html" "chevron_right" }}</span>
+     <span>Introduced in {{ T $component }} version
+     {{- if $link }}
+       {{ page.RenderString (fmt.Printf `[%s](%s)` $v $link) }}
+     {{- else }}
+       {{ $v }}
+     {{- end }}
+     </span>
+  </div>
+  {{- else }}
+    {{ warnf "[introduced] version below threshold: %s %s %v" $component $v $pos }}
+  {{- end }}
+{{- else }}
+  {{ errorf "[introduced] invalid component: %s %v" $component $pos }}
+{{- end }}