[docs]: fix mismatch in release tags by documenting stable and dev tags seperately.

README.md

@@ -37,8 +37,12 @@ If you want to create your own image or add functionality on top of the images a
 
 This repository contains a select set of images, and we encourage the community to host and share additional images, and features rather than adding them here. You may learn more about this process in [the guidance](https://containers.dev/implementors/features-distribution/) in our spec repo. You may also check out the [features](https://github.com/devcontainers/features) repo for additional customizations you may adopt or modify for your dev containers.
 
+When changing an existing image, update its `manifest.json` version as required by the change, but do not manually update fully pinned release-tag examples in the image README, including for security and bug-fix updates. Release preparation applies the final patch bump and updates the README's pinned release tags to match the final manifest version. Development tags use the `dev-*` channel from `main`; update the Development tags section only when an available development tag name or variant changes.
+
 ## Feedback
 
+Before opening an issue about a stable image tag, check the matching development tag (`dev-*`) first: it is built from `main` and may already include a fix that has not reached a stable release.
+
 Issues related to these images can be reported in [an issue](https://github.com/devcontainers/images/issues) in this repository.
 
 # License

build/prepare-release.sh

@@ -54,26 +54,28 @@ update_readme_version() {
 		return
 	fi
 
-	# Extract major.minor from the version
-	majorMinor=$(echo "$oldVersion" | cut -d. -f1,2)
-	# Escape dots for use in sed/grep regex patterns so they match literal dots only
-	majorMinorEscaped=$(echo "$majorMinor" | sed 's/\./\\./g')
-
-	# Check if major.minor version pattern exists in README
-	# Match :major.minor.patch followed by either - (variant) or ` (backtick)
-	if ! grep -qE ":${majorMinorEscaped}\.[0-9]+[-\`]" "$readmePath"; then
-		echo "ERROR: Version pattern ${majorMinor}.x not found in $readmePath"
+	# Only stable, pinned tags are release-versioned. Development tags describe main.
+	if ! awk '
+		/^### Pinned release tags$/ { in_pinned_section = 1; next }
+		in_pinned_section && /^#/ { exit }
+		in_pinned_section { print }
+	' "$readmePath" | grep -qE ":[0-9]+\.[0-9]+\.[0-9]+[-\`]"; then
+		echo "ERROR: Pinned release version pattern not found in $readmePath"
 		exit 1
 	fi
 
-	# Update full version references (e.g., 1.3.x-variant -> 1.3.3-variant, or 1.3.x` -> 1.3.3`)
-	# The pattern matches major.minor.any_patch followed by - (variant) or ` (backtick)
-	# We match after : (full image reference) or after ` (shortened tag examples)
-	sed -i "s/:${majorMinorEscaped}\.[0-9]*-/:${newVersion}-/g" "$readmePath"
-	sed -i "s/:${majorMinorEscaped}\.[0-9]*\`/:${newVersion}\`/g" "$readmePath"
-	sed -i "s/\`${majorMinorEscaped}\.[0-9]*-/\`${newVersion}-/g" "$readmePath"
+	awk -v newVersion="$newVersion" '
+		/^### Pinned release tags$/ { in_pinned_section = 1 }
+		in_pinned_section && /^#/ && $0 != "### Pinned release tags" { in_pinned_section = 0 }
+		in_pinned_section {
+			gsub(":[0-9]+\\.[0-9]+\\.[0-9]+-", ":" newVersion "-")
+			gsub(":[0-9]+\\.[0-9]+\\.[0-9]+`", ":" newVersion "`")
+			gsub("`[0-9]+\\.[0-9]+\\.[0-9]+-", "`" newVersion "-")
+		}
+		{ print }
+	' "$readmePath" > "$readmePath.tmp" && mv "$readmePath.tmp" "$readmePath"
 
-	echo "Updated README.md version references from ${majorMinor}.x to $newVersion"
+	echo "Updated pinned README.md version references to $newVersion"
 }
 
 release_image() {

build/test-prepare-release.sh

@@ -45,38 +45,58 @@ run_test() {
 }
 
 # ---------------------------------------------------------------------------
-# Test 1: Go-style tags – major tag (2-1.26) must NOT be touched; only the
-# patch tag (2.1.3-1.26) should become the new version (2.1.4-1.26).
-# This is the regression case: unescaped dots in the sed pattern caused
-# `2-1.26` to match `2.1` (dot = any char) and get incorrectly rewritten.
+# Test 1: Only semantic tags in the pinned release section are updated.
+# Development tags and major release tags must remain unchanged.
 # ---------------------------------------------------------------------------
-run_test "go_major_tag_not_rewritten" \
+run_test "updates_only_pinned_release_tags" \
 	"2.1.3" \
 	"2.1.4" \
-	"- \`mcr.microsoft.com/devcontainers/go:2-1.26\` (or \`2-1.26-trixie\`, \`2-1.26-bookworm\`)
+	"### Release tags
+- \`mcr.microsoft.com/devcontainers/go:2-1.26\`
+
+### Development tags (\`dev-*\`)
+- \`mcr.microsoft.com/devcontainers/go:dev-1.26\`
+
+### Pinned release tags
 - \`mcr.microsoft.com/devcontainers/go:2.1-1.26\` (or \`2.1-1.26-trixie\`, \`2.1-1.26-bookworm\`)
-- \`mcr.microsoft.com/devcontainers/go:2.1.3-1.26\` (or \`2.1.3-1.26-trixie\`, \`2.1.3-1.26-bookworm\`)" \
-	"- \`mcr.microsoft.com/devcontainers/go:2-1.26\` (or \`2-1.26-trixie\`, \`2-1.26-bookworm\`)
+- \`mcr.microsoft.com/devcontainers/go:2.1.3-1.26\` (or \`2.1.3-1.26-trixie\`, \`2.1.3-1.26-bookworm\`)
+
+## Other guidance
+- \`mcr.microsoft.com/devcontainers/go:2.1.3-unchanged\`" \
+	"### Release tags
+- \`mcr.microsoft.com/devcontainers/go:2-1.26\`
+
+### Development tags (\`dev-*\`)
+- \`mcr.microsoft.com/devcontainers/go:dev-1.26\`
+
+### Pinned release tags
 - \`mcr.microsoft.com/devcontainers/go:2.1-1.26\` (or \`2.1-1.26-trixie\`, \`2.1-1.26-bookworm\`)
-- \`mcr.microsoft.com/devcontainers/go:2.1.4-1.26\` (or \`2.1.4-1.26-trixie\`, \`2.1.4-1.26-bookworm\`)"
+- \`mcr.microsoft.com/devcontainers/go:2.1.4-1.26\` (or \`2.1.4-1.26-trixie\`, \`2.1.4-1.26-bookworm\`)
+
+## Other guidance
+- \`mcr.microsoft.com/devcontainers/go:2.1.3-unchanged\`"
 
 # ---------------------------------------------------------------------------
 # Test 2: Standard backtick-terminated patch tag is updated correctly.
 # ---------------------------------------------------------------------------
 run_test "patch_backtick_tag_updated" \
 	"2.1.3" \
 	"2.1.4" \
-	"- \`mcr.microsoft.com/devcontainers/go:2.1.3\` (latest patch)" \
-	"- \`mcr.microsoft.com/devcontainers/go:2.1.4\` (latest patch)"
+	"### Pinned release tags
+- \`mcr.microsoft.com/devcontainers/go:2.1.3\` (latest patch)" \
+	"### Pinned release tags
+- \`mcr.microsoft.com/devcontainers/go:2.1.4\` (latest patch)"
 
 # ---------------------------------------------------------------------------
 # Test 3: Colon-prefixed patch tag with variant suffix is updated.
 # ---------------------------------------------------------------------------
 run_test "patch_colon_variant_tag_updated" \
 	"1.3.5" \
 	"1.3.6" \
-	"mcr.microsoft.com/devcontainers/python:1.3.5-bullseye" \
-	"mcr.microsoft.com/devcontainers/python:1.3.6-bullseye"
+	"### Pinned release tags
+mcr.microsoft.com/devcontainers/python:1.3.5-bullseye" \
+	"### Pinned release tags
+mcr.microsoft.com/devcontainers/python:1.3.6-bullseye"
 
 # ---------------------------------------------------------------------------
 # Test 4: mid-line backtick-prefixed patch tag with variant is updated.
@@ -85,11 +105,25 @@ run_test "patch_colon_variant_tag_updated" \
 run_test "patch_backtick_variant_tag_updated" \
 	"3.0.1" \
 	"3.0.2" \
-	"- \`mcr.microsoft.com/devcontainers/base:3.0.1-bookworm\`
+	"### Pinned release tags
+- \`mcr.microsoft.com/devcontainers/base:3.0.1-bookworm\`
 - Use \`3.0.1-bookworm\` for the stable variant." \
-	"- \`mcr.microsoft.com/devcontainers/base:3.0.2-bookworm\`
+	"### Pinned release tags
+- \`mcr.microsoft.com/devcontainers/base:3.0.2-bookworm\`
 - Use \`3.0.2-bookworm\` for the stable variant."
 
+# ---------------------------------------------------------------------------
+# Test 5: The updater replaces the previous semantic tag with the final manifest
+# version even when a contributor made a major or minor version change first.
+# ---------------------------------------------------------------------------
+run_test "arbitrary_manifest_version_transition" \
+	"3.1.6" \
+	"4.0.1" \
+	"### Pinned release tags
+- \`mcr.microsoft.com/devcontainers/anaconda:3.1.6-3\`" \
+	"### Pinned release tags
+- \`mcr.microsoft.com/devcontainers/anaconda:4.0.1-3\`"
+
 # ---------------------------------------------------------------------------
 # Summary
 # ---------------------------------------------------------------------------

src/anaconda/README.md

@@ -18,14 +18,22 @@ See **[history](history)** for information on the contents of published images.
 
 ## Using this image
 
-### Configuration
-
-You can directly reference pre-built versions of `.devcontainer/Dockerfile` by using the `image` property in `.devcontainer/devcontainer.json` or updating the `FROM` statement in your own `Dockerfile` to the following. An example `Dockerfile` is included in this repository.
+### Release tags
 
 - `mcr.microsoft.com/devcontainers/anaconda`
 
+#### Configuration
+
+You can directly reference pre-built versions of `.devcontainer/Dockerfile` by using the `image` property in `.devcontainer/devcontainer.json` or updating the `FROM` statement in your own `Dockerfile` to the above. An example `Dockerfile` is included in this repository.
+
 Refer to [this guide](https://containers.dev/guide/dockerfile) for more details.
 
+### Development tags (`dev-*`)
+
+Development tags are preview builds from `main`, not stable release artifacts. Use `mcr.microsoft.com/devcontainers/anaconda:dev-3` to test the current image definition before its next stable release. Before reporting an issue or reviewing a fix against a stable tag, check the development tag because a merged change may already be available there.
+
+### Pinned release tags
+
 You can decide how often you want updates by referencing a [semantic version](https://semver.org/) of each image. For example:
 
 - `mcr.microsoft.com/devcontainers/anaconda:1-3`

src/base-alpine/README.md

@@ -9,7 +9,7 @@
 | *Categories* | Core, Other |
 | *Image type* | Dockerfile |
 | *Published images* | mcr.microsoft.com/devcontainers/base:alpine |
-| *Available image variants* | alpine-3.23, alpine-3.22, alpine-3.21 ([full list](https://mcr.microsoft.com/v2/devcontainers/base/tags/list)) |
+| *Available image variants* | alpine3.23, alpine3.22, alpine3.21 ([full list](https://mcr.microsoft.com/v2/devcontainers/base/tags/list)) |
 | *Published image architecture(s)* | x86-64, aarch64/arm64 |
 | *Container host OS support* | Linux, macOS, Windows |
 | *Container OS* | Alpine Linux |
@@ -19,16 +19,24 @@ See **[history](history)** for information on the contents of published images.
 
 ## Using this image
 
+### Release tags
+
 You can also directly reference pre-built versions of `.devcontainer/Dockerfile` by using the `image` property in `.devcontainer/devcontainer.json` or updating the `FROM` statement in your own  `Dockerfile` to one of the following. An example `Dockerfile` is included in this repository.
 
 - `mcr.microsoft.com/devcontainers/base:alpine` (latest)
-- `mcr.microsoft.com/devcontainers/base:alpine-3.23`
-- `mcr.microsoft.com/devcontainers/base:alpine-3.22`
-- `mcr.microsoft.com/devcontainers/base:alpine-3.21`
+- `mcr.microsoft.com/devcontainers/base:alpine3.23`
+- `mcr.microsoft.com/devcontainers/base:alpine3.22`
+- `mcr.microsoft.com/devcontainers/base:alpine3.21`
 
 
 Refer to [this guide](https://containers.dev/guide/dockerfile) for more details.
 
+### Development tags (`dev-*`)
+
+Development tags are preview builds from `main`. Use `mcr.microsoft.com/devcontainers/base:dev-alpine` to test the current Alpine image definition before its next stable release.
+
+### Pinned release tags
+
 You can decide how often you want updates by referencing a [semantic version](https://semver.org/) of each image. For example:
 
 - `mcr.microsoft.com/devcontainers/base:4-alpine`

src/base-debian/README.md

@@ -19,6 +19,8 @@ See **[history](history)** for information on the contents of published images.
 
 ## Using this image
 
+### Release tags
+
 You can directly reference pre-built versions of `Dockerfile` by using the `image` property in `.devcontainer/devcontainer.json` or updating the `FROM` statement in your own `Dockerfile` to one of the following. An example `Dockerfile` is included in this repository.
 
 - `mcr.microsoft.com/devcontainers/base:debian` (latest)
@@ -27,6 +29,12 @@ You can directly reference pre-built versions of `Dockerfile` by using the `imag
 
 Refer to [this guide](https://containers.dev/guide/dockerfile) for more details.
 
+### Development tags (`dev-*`)
+
+Development tags are preview builds from `main`. Use `mcr.microsoft.com/devcontainers/base:dev-debian` to test the current Debian image definition before its next stable release.
+
+### Pinned release tags
+
 You can decide how often you want updates by referencing a [semantic version](https://semver.org/) of each image. For example:
 
 - `mcr.microsoft.com/devcontainers/base:2-trixie`

src/base-ubuntu/README.md

@@ -19,6 +19,8 @@ See **[history](history)** for information on the contents of published images.
 
 ## Using this image
 
+### Release tags
+
 You can directly reference pre-built versions of `Dockerfile` by using the `image` property in `.devcontainer/devcontainer.json` or updating the `FROM` statement in your own `Dockerfile` to one of the following. An example `Dockerfile` is included in this repository.
 
 - `mcr.microsoft.com/devcontainers/base:ubuntu` (latest LTS release)
@@ -28,6 +30,12 @@ You can directly reference pre-built versions of `Dockerfile` by using the `imag
 
 Refer to [this guide](https://containers.dev/guide/dockerfile) for more details.
 
+### Development tags (`dev-*`)
+
+Development tags are preview builds from `main`. Use `mcr.microsoft.com/devcontainers/base:dev-ubuntu` to test the current Ubuntu image definition before its next stable release.
+
+### Pinned release tags
+
 You can decide how often you want updates by referencing a [semantic version](https://semver.org/) of each image. For example:
 
 - `mcr.microsoft.com/devcontainers/base:3-jammy`

src/cpp/README.md

@@ -19,6 +19,8 @@ See **[history](history)** for information on the contents of published images.
 
 ## Using this image
 
+### Release tags
+
 You can directly reference pre-built versions of `Dockerfile` by using the `image` property in `.devcontainer/devcontainer.json` or updating the `FROM` statement in your own  `Dockerfile` to one of the following. An example `Dockerfile` is included in this repository.
 
 - `mcr.microsoft.com/devcontainers/cpp` (latest Debian GA)
@@ -32,6 +34,12 @@ You can directly reference pre-built versions of `Dockerfile` by using the `imag
 
 Refer to [this guide](https://containers.dev/guide/dockerfile) for more details.
 
+### Development tags (`dev-*`)
+
+Development tags are preview builds from `main`. Use `mcr.microsoft.com/devcontainers/cpp:dev-debian` to test the current image definition before its next stable release.
+
+### Pinned release tags
+
 You can decide how often you want updates by referencing a [semantic version](https://semver.org/) of each image. For example:
 - `mcr.microsoft.com/devcontainers/cpp:3-trixie`
 - `mcr.microsoft.com/devcontainers/cpp:3.0-trixie`

src/dotnet/README.md

@@ -19,6 +19,8 @@ See **[history](history)** for information on the contents of published images.
 
 ## Using this image
 
+### Release tags
+
 You can directly reference pre-built versions of `Dockerfile` by using the `image` property in `.devcontainer/devcontainer.json` or updating the `FROM` statement in your own  `Dockerfile` to one of the following. An example `Dockerfile` is included in this repository.
 
 - `mcr.microsoft.com/devcontainers/dotnet` (latest)
@@ -30,6 +32,12 @@ You can directly reference pre-built versions of `Dockerfile` by using the `imag
 
 Refer to [this guide](https://containers.dev/guide/dockerfile) for more details.
 
+### Development tags (`dev-*`)
+
+Development tags are preview builds from `main`. Use `mcr.microsoft.com/devcontainers/dotnet:dev-10.0-noble` to test the current image definition before its next stable release.
+
+### Pinned release tags
+
 You can decide how often you want updates by referencing a [semantic version](https://semver.org/) of each image. For example:
 
 - `mcr.microsoft.com/devcontainers/dotnet:2-10.0-noble`

src/go/README.md

@@ -20,6 +20,8 @@ See **[history](history)** for information on the contents of published images.
 
 ## Using this image
 
+### Release tags
+
 You can directly reference pre-built versions of `Dockerfile` by using the `image` property in `.devcontainer/devcontainer.json` or updating the `FROM` statement in your own  `Dockerfile` to one of the following. An example `Dockerfile` is included in this repository.
 
 - `mcr.microsoft.com/devcontainers/go` (latest)
@@ -30,6 +32,12 @@ You can directly reference pre-built versions of `Dockerfile` by using the `imag
 
 Refer to [this guide](https://containers.dev/guide/dockerfile) for more details.
 
+### Development tags (`dev-*`)
+
+Development tags are preview builds from `main`. Use `mcr.microsoft.com/devcontainers/go:dev-1.27` to test the current image definition before its next stable release.
+
+### Pinned release tags
+
 You can decide how often you want updates by referencing a [semantic version](https://semver.org/) of each image. For example:
 
 - `mcr.microsoft.com/devcontainers/go:2-1.27` (or `2-1.27-trixie`, `2-1.27-bookworm`)

src/java-8/README.md

@@ -19,6 +19,8 @@ See **[history](history)** for information on the contents of published images.
 
 ## Using this image
 
+### Release tags
+
 > **Note:** A version of this [image for **newer JDKs**](../java) is also available!
 
 You can directly reference pre-built versions of `Dockerfile` by using the `image` property in `.devcontainer/devcontainer.json` or updating the `FROM` statement in your own  `Dockerfile` to one of the following. An example `Dockerfile` is included in this repository.
@@ -27,6 +29,12 @@ You can directly reference pre-built versions of `Dockerfile` by using the `imag
 
 Refer to [this guide](https://containers.dev/guide/dockerfile) for more details.
 
+### Development tags (`dev-*`)
+
+Development tags are preview builds from `main`. Use `mcr.microsoft.com/devcontainers/java:dev-8` to test the current image definition before its next stable release.
+
+### Pinned release tags
+
 You can decide how often you want updates by referencing a [semantic version](https://semver.org/) of each image. For example:
 
 - `mcr.microsoft.com/devcontainers/java:3-8` (or `3-8-trixie`, `3-8-bookworm` to pin to an OS version)

src/java/README.md

@@ -19,6 +19,8 @@ See **[history](history)** for information on the contents of published images.
 
 ## Using this image
 
+### Release tags
+
 You can directly reference pre-built versions of `Dockerfile` by using the `image` property in `.devcontainer/devcontainer.json` or updating the `FROM` statement in your own  `Dockerfile` to one of the following. An example `Dockerfile` is included in this repository.
 
 - `mcr.microsoft.com/devcontainers/java` (latest)
@@ -29,6 +31,12 @@ You can directly reference pre-built versions of `Dockerfile` by using the `imag
 
 Refer to [this guide](https://containers.dev/guide/dockerfile) for more details.
 
+### Development tags (`dev-*`)
+
+Development tags are preview builds from `main`. Use `mcr.microsoft.com/devcontainers/java:dev-11` to test the current image definition before its next stable release.
+
+### Pinned release tags
+
 You can decide how often you want updates by referencing a [semantic version](https://semver.org/) of each image. For example:
 
 - `mcr.microsoft.com/devcontainers/java:3-11` (or `3-11-trixie`, `3-11-bookworm` to pin to an OS version)

src/javascript-node/README.md

@@ -17,6 +17,8 @@
 
 ## Using this image
 
+### Release tags
+
 You can directly reference pre-built versions of `Dockerfile` by using the `image` property in `.devcontainer/devcontainer.json` or updating the `FROM` statement in your own  `Dockerfile` to one of the following. An example `Dockerfile` is included in this repository.
 
 - `mcr.microsoft.com/devcontainers/javascript-node` (latest)
@@ -26,6 +28,12 @@ You can directly reference pre-built versions of `Dockerfile` by using the `imag
 
 Refer to [this guide](https://containers.dev/guide/dockerfile) for more details.
 
+### Development tags (`dev-*`)
+
+Development tags are preview builds from `main`. Use `mcr.microsoft.com/devcontainers/javascript-node:dev-26` to test the current image definition before its next stable release.
+
+### Pinned release tags
+
 You can decide how often you want updates by referencing a [semantic version](https://semver.org/) of each image. For example:
 
 - `mcr.microsoft.com/devcontainers/javascript-node:5-24` (or `5-24-trixie`, `5-24-bookworm`)