docs: clarify Docker 29.x Dev Containers hang root cause and fix

[keivenchang]

Overview:

Clarifies the Docker 29.x Dev Containers compatibility issue by documenting the actual root cause, affected versions, and the fix.

Details:

• Replaced vague "compatibility issues" with specific symptom: IDE hangs after "Container started", postCreateCommand never runs
• Documented root cause: Docker 29.x emits "Action" instead of "status" in docker events JSON output, causing the devcontainers CLI (v0.75.0) to silently discard the start event
• Listed affected versions (Docker 29.0.0+ with extension v1.0.26) and fix (extension v1.0.32+)
• Added confirmed working version combinations
• Updated recommended fix: upgrade extension rather than downgrade Docker

Where should the reviewer start?

• .devcontainer/README.md — the only file changed

Related Issues:

Fixes DIS-1497

/coderabbit profile chill

Summary by CodeRabbit

• Documentation
  • Updated Docker compatibility guidance with detailed information about Docker 29.x compatibility and recommended version combinations.
  • Added troubleshooting information for IDE issues and clear upgrade paths to resolve them.

[coderabbitai]

Walkthrough

The .devcontainer/README.md file documentation was updated to replace generic Docker version compatibility guidance with a specific technical narrative addressing Docker 29.x incompatibility with earlier Dev Containers extension versions, including root cause analysis, affected configurations, and recommended workarounds.

Changes

Cohort / File(s)	Summary
Docker Compatibility Documentation .devcontainer/README.md	Replaced general Docker version notes with detailed Docker 29.x incompatibility documentation. Added diagnostic information covering symptoms (IDE hangs, postCreateCommand failures), root cause (event data format change), affected/fixed versions, and confirmed workaround combinations (Docker 27.x/28.x with any extension version, or Docker 29.x with Dev Containers v1.0.32+).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A Docker tale retold with care,
Where versions dance through devcontainer air,
Twenty-nine brought puzzles, but we found the way,
Point three-two's the answer, hip-hop hooray! 🎉

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: clarifying Docker 29.x Dev Containers hang root cause and fix in documentation.
Description check	✅ Passed	The description follows the template structure with Overview, Details, Where should the reviewer start, and Related Issues sections properly filled out.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

.devcontainer/README.md (1)

14-24: Add a link to the upstream issue/PR for traceability.

The new section is specific and useful, but providing a link to the upstream GitHub issue (e.g., microsoft/vscode-remote-release or devcontainers/cli) or the extension changelog entry that fixed this in v1.0.32 would allow readers to verify the details independently and monitor for related regressions.

✏️ Example addition

 **Recommended fix:** If you are using Docker 29.x, update the Dev Containers extension to **v1.0.32 or later**. Docker Engine 28.5.2 or earlier have been stable with all extension versions.
+
+> See the relevant upstream fix at [microsoft/vscode-remote-release](https://github.com/microsoft/vscode-remote-release/issues) for full discussion.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.devcontainer/README.md around lines 14 - 24, Add a direct link to the
upstream issue/PR or changelog that documents the Docker 29.x incompatibility
and the Dev Containers v1.0.32 fix in the Docker 29.x section of
.devcontainer/README.md (the "Docker 29.x had a known incompatibility..."
paragraph); update the "Fixed in: Dev Containers extension v1.0.32+" line to
include the full URL to the GitHub issue/PR or the extension changelog
(preferably microsoft/vscode-remote-release or devcontainers/cli PR/issue and
the v1.0.32 changelog entry) and include the issue/PR number in the link text
for traceability.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.devcontainer/README.md:
- Line 21: The README line "Docker 27.x / 28.x with any extension version" is
too broad; update that sentence to scope the Dev Containers extension version
tested (e.g., "Docker 27.x / 28.x with Dev Containers extension v1.0.26+"), or
alternatively state an explicit tested range and add a short note that older
extension versions may be incompatible; locate and replace the exact string
"Docker 27.x / 28.x with any extension version" in .devcontainer/README.md and
include the chosen minimum version or tested range in the same sentence.
- Line 17: Update the README text around the root cause so the extension/CLI
version mapping is verified and upstream references are added: confirm whether
"extension v1.0.32" actually bundles devcontainers/cli v0.80.2 (or update the
extension version mentioned), and add links to devcontainers/cli PR `#1103`, the
devcontainers/cli CHANGELOG entry for v0.80.2, and the Docker Engine v29 release
notes; edit the sentence that currently names "extension v1.0.32+" and "v1.0.26
(bundling CLI v0.75.0)" to either correct the mapping or clarify the mapping
methodology and include the three upstream references for verifiability.

---

Nitpick comments:
In @.devcontainer/README.md:
- Around line 14-24: Add a direct link to the upstream issue/PR or changelog
that documents the Docker 29.x incompatibility and the Dev Containers v1.0.32
fix in the Docker 29.x section of .devcontainer/README.md (the "Docker 29.x had
a known incompatibility..." paragraph); update the "Fixed in: Dev Containers
extension v1.0.32+" line to include the full URL to the GitHub issue/PR or the
extension changelog (preferably microsoft/vscode-remote-release or
devcontainers/cli PR/issue and the v1.0.32 changelog entry) and include the
issue/PR number in the link text for traceability.

---

ℹ️ Review info

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between cb55766 and 8a0311d.

📒 Files selected for processing (1)

• .devcontainer/README.md