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

Summary

Clarifies stable and experimental dev-* image availability across all image READMEs and directs users to live MCR data for currently pullable tags.

Addresses #1965.

Current Issue ( For detailed report refer #1965 )

Development and stable images follow separate publication flows:

• Dev images are built from main and published under mutable dev-* tags.
• Stable images are published through the dedicated versioned release flow.
• prepare-release.sh applies the manifest patch bump and rewrites matching README version examples during release preparation.

Repository changes can therefore reach main before stable publication, causing static README examples to temporarily reference tags that are not yet pullable.

Changes

• Updated all 18 image READMEs to:
  • provide a copyable latest stable image reference;
  • link separately to its MCR details;
  • link to MCR Tags for other available versions;
  • include one valid experimental dev-* example;
  • explain that dev tags may be updated in place;
  • recommend pinning experimental images for reproducibility;
  • identify existing semantic-version references as usage examples.
• Added contributor and Copilot guidance requiring:
  • every image change to bump manifest.json using semantic versioning;
  • README pin updates for major and minor version bumps;
  • no README pin updates for routine security patch bumps.

Approaches Considered

1. Lifecycle-Aware README Sections and Release Script

Split each README into release tags, dev-* preview tags, and pinned stable tags. Update prepare-release.sh to rewrite only the pinned stable section.

Pros

• Preserves automatic stable-version pin updates.
• Prevents the script from modifying unrelated README content.
• Gives stable, dev, and pinned tags explicit documentation boundaries.

Cons

• Introduces a rigid Markdown-heading contract requiring dedicated tests and maintenance.
• Pins still change before MCR publication succeeds, so failed releases can leave them ahead of the registry.

2A. Separate Stable and Dev Documentation

Maintain separate README records for stable and dev-* tags. Stable examples update during release preparation, while dev examples are updated before dev publication.

Pros

• Clearly separates stable and experimental artifacts.
• Keeps dev variants documented before stable release.
• Allows each tag type to follow its own lifecycle.

Cons

• Adds recurring documentation work before scheduled and manual dev pushes.
• Duplicates MCR tag data while creating another synchronization point.

Maintainers considered this ineffective because MCR already provides a registry-backed tag inventory. If dev variants remain undocumented until stable release, their early-discovery and validation value is significantly reduced.

2B. Update READMEs Only During Stable Releases

Developers update manifests without changing README tags. Release automation updates README references during stable release preparation.

Pros

• Prevents development changes from immediately appearing as stable examples.
• Reduces README edits during development.
• Allows release automation to use the calculated final version.

Cons

• Dev variants can be published without being discoverable in repository documentation.
• Post-publication updates require additional commits, documentation PRs, rollback handling, and workflow state.

2C. Use MCR for Current Availability

Keep semantic-version examples in READMEs while directing users to the latest stable artifact and live MCR Tags page. Include one representative dev-* tag per image.

Pros

• Uses registry-backed data for currently pullable tags, digests, and publication state.
• Keeps stable and experimental images discoverable without another publication gate.
• Requires no new release-state, rollback, or documentation-PR automation.

Cons

• Static semantic-version examples can briefly lead stable publication.
• Users must consult MCR when selecting a currently available version.

Why We Selected 2C

• It preserves the purpose of dev images: early discovery and validation of changes from main.
• It separates copyable image references from browser links.
• Major and minor changes remain visible and flow into dev builds before stable publication.
• Existing preview builds can catch image and variant errors before the same content becomes stable.
• Routine security patch releases avoid unnecessary README pin churn.
• It resolves the user-facing ambiguity without increasing release-workflow complexity & during the meeting the team had come to a conclusion that this is the best option for now. (The caveats will be addressed in future)

Validation

• Confirmed all documented stable references exist on MCR.
• Confirmed all documented dev-* examples exist on MCR.
• Verified the final wording across all 18 image READMEs.
• git diff --check

Caveat

Static semantic-version examples may still briefly lead stable publication, and users must consult MCR for current availability. The existing release automation remains unchanged; lifecycle-aware post-publication updates could eliminate this window in the future if the additional workflow complexity becomes justified.