# Bug: README stable-tag examples precede MCR publication

## Problem

Review requires README tag examples to stay consistent with `manifest.json`, which is correct because it documents supported variants, prevents stale configuration guidance, and lets reviewers verify that tag examples match the image definition. Those examples must also match tags users can actually pull from MCR. However, `manifest.json` changes merge to `main` before their stable MCR images are released. This makes the README advertise planned stable tags that users cannot pull.

For example, `typescript-node` documents `:26`, but MCR currently provides only `:dev-26`.

The current Anaconda version in the README is `1.4.0` (following a minor bump from `1.3.24`). However, the latest published Anaconda version is only `:1.3.24-3`, hosted on [MCR](https://mcr.microsoft.com/en-us/artifact/mar/devcontainers/anaconda/tag/latest). In addition to this inconsistency, the build adds a patch version for the release artifact, so the next release will be `1.4.1`. Therefore, the 1.4.0 version currently mentioned in the README is incorrect and will stay incorrect even when new release happens. Similar issue is present in other images as well.

## Impact

Users follow README instructions and receive an image-not-found error. The README is internally consistent with the development manifest but incorrect relative to published MCR tags for much of the release cycle.

One of the users have reported the same at [#1963](https://github.com/devcontainers/images/issues/1963)

## Root Cause

`build/prepare-release.sh` automatically rewrites README tag examples from the next `manifest.json` version during release preparation. It was intended to add released-version examples automatically, but it runs before stable MCR publication is confirmed and therefore treats a planned version as pullable.

Removing this rewrite fixes the ordering problem, but also completely removes the existing automatic README bump. After MCR publication, a maintainer must verify the tags and manually update stable and pinned README references in a documentation PR.

## Approaches

### 1. Manual development and stable tag updates

Document development and stable tags as separate README sections. A maintainer updates the `dev-*` section when a development image is published from `main`, and updates the stable semantic and pinned tags when a `v*` release is published.

**Major impact:** Removes the automatic README rewrite from `build/prepare-release.sh`.

**Impact and severity:** The least complex option and accurately reflects the two publication events, but adds recurring manual documentation work. **Severity: low implementation and operational risk; medium process burden.**

### 2. Lifecycle-aware README update script

Keep the README sections separate and adapt the existing update script. At each manually started publication workflow, the maintainer selects whether it is a development or stable release. The script updates only the corresponding README section and derives the expected tags from the final `manifest.json` version, including the patch increment performed by `prepare-release.sh`.

The manifest patch increment should remain the release-versioning policy unless maintainers decide otherwise: a committed `4.1.0` becomes the release artifact `4.1.1`, so the script must use the post-bump version rather than the version originally present in the PR.

**Major impact:** Changes the existing release-preparation script and adds a release-type selection to the publication workflow.

**Impact and severity:** Preserves simple automation and accounts for the separate development and stable tag lifecycles. However, it assumes the release succeeds. If a build or release fails, the README retains inconsistent expected tags until a maintainer manually reverts the affected update. **Severity: moderate implementation effort; moderate operational risk.**

### 3. Lifecycle-aware update with automatic rollback

Build on option 2, but make the release workflow automatically revert the README update when the corresponding development or stable publication fails.

**Major impact:** Adds failure-handling and write-back behavior to publication workflows.

**Impact and severity:** Prevents a failed publication from leaving expected but unavailable tags in documentation, but makes the release path more complex and requires careful handling of concurrent README changes. **Severity: high implementation and operational complexity.**

### 4. Dependabot-style documentation pull requests

Generate a dedicated automated PR for each development or stable publication event. The PR updates only the matching README section, based on the final manifest version and selected release type, and retains normal review and merge controls.

**Major impact:** Adds a GitHub App or workflow automation that creates and manages documentation PRs.

**Impact and severity:** Provides a clear audit trail and avoids direct workflow writes to `main`, but has the highest setup and maintenance cost. **Severity: high implementation effort; lower direct-write risk.**