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. 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
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.
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.jsonchanges merge tomainbefore their stable MCR images are released. This makes the README advertise planned stable tags that users cannot pull.For example,
typescript-nodedocuments:26, but MCR currently provides only:dev-26.The current Anaconda version in the README is
1.4.0(following a minor bump from1.3.24). However, the latest published Anaconda version is only:1.3.24-3, hosted on MCR. In addition to this inconsistency, the build adds a patch version for the release artifact, so the next release will be1.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
Root Cause
build/prepare-release.shautomatically rewrites README tag examples from the nextmanifest.jsonversion 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 frommain, and updates the stable semantic and pinned tags when av*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.jsonversion, including the patch increment performed byprepare-release.sh.The manifest patch increment should remain the release-versioning policy unless maintainers decide otherwise: a committed
4.1.0becomes the release artifact4.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.