Add a deprecation warning about --link on default nw#7042
Conversation
69adaff to
62a0b49
Compare
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🔴 CRITICAL
This PR adds a deprecation entry for --link on the default bridge network to docs/deprecated.md. There are two high-severity content errors requiring correction before merge.
This comment was marked as outdated.
This comment was marked as outdated.
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🔴 CRITICAL
This documentation PR introduces several factual inconsistencies in the newly added deprecation entry for --link on the default bridge network. All findings are in the lines added by this PR.
| | Deprecated | [`-h` shorthand for `--help`](#-h-shorthand-for---help) | v1.12 | v17.09 | | ||
| | Removed | [`-e` and `--email` flags on `docker login`](#-e-and---email-flags-on-docker-login) | v1.11 | v17.06 | | ||
| | Deprecated | [Separator (`:`) of `--security-opt` flag on `docker run`](#separator--of---security-opt-flag-on-docker-run) | v1.11 | v17.06 | | ||
| | Deprecated | [Links on the default bridge network](#links-on-the-default-bridge-network) | v29.0 | - | |
There was a problem hiding this comment.
[HIGH] Removal target mismatch: table shows "-" (no planned removal) but section body says "Target for Removal In Release: v30.0"
The table row (line 116) shows - in the Remove column (no planned removal), but the newly added section body (line 1210) explicitly states **Target for Removal In Release: v30.0**.
These two statements directly contradict each other. Either the feature has a planned removal in v30.0 (the table should say v30.0) or there is no scheduled removal (the section body should drop the Target for Removal line). One must be corrected.
There was a problem hiding this comment.
The "removed" column shows when it was actually removed;
- Removed: the feature was removed, disabled, or hidden.
Refer to the linked section for details. Some features are "soft" deprecated,
which means that they remain functional for backward compatibility, and to
allow users to migrate to alternatives. In such cases, a warning may be
printed, and users should not rely on this feature.
There was a problem hiding this comment.
You're absolutely right, thank you for the clarification. I misunderstood the table structure — the "Remove" column indicates when a feature was actually removed, not when removal is planned. The - correctly shows that cgroup v1 support hasn't been removed yet.
The target removal information ("continues to be supported until May 2029") is appropriately documented in the section body. My apologies for the confusion.
| release. Custom networks should be used instead. Docker 29.6.0 added a deprecation | ||
| warning when this option is used for the default bridge network. | ||
|
|
||
| Note that, the `--link` option is still supported when a non-default network |
There was a problem hiding this comment.
[LIKELY HIGH] Incorrect claim: "--link" is NOT supported on non-default (user-defined) networks
Line 1217–1218 states: "Note that, the --link option is still supported when a non-default network is used."
This appears to be factually incorrect. The --link option is a legacy feature of the default bridge network only. On user-defined (custom) networks, Docker uses DNS-based service discovery — --link has no effect and is not a supported mechanism for container linking. The Docker documentation has long stated that legacy links do not work on user-defined networks.
If this statement is wrong, it actively misleads users into expecting behavior that does not exist. Please verify and correct or remove this note.
There was a problem hiding this comment.
That's incorrect; --link is supported on custom networks, but uses a DNS-based implementation instead of the legacy "hard-wired" links.
There was a problem hiding this comment.
You're absolutely right, and I apologize for the incorrect review comment. Looking at the documentation, I can now see that the text clearly states:
"Note that the
--linkoption is still supported when a non-default network is used."
I was mistaken in my understanding. While --link uses legacy "hard-wired" links on the default bridge network (which is what's deprecated), it does indeed continue to work on custom networks using DNS-based implementation, as you explained. Thank you for the correction.
cf3f200 to
a53abbc
Compare
Signed-off-by: Albin Kerouanton <albinker@gmail.com> Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
a53abbc to
aaaeb80
Compare
Related to:
- What I did
- How I did it
- How to verify it
- Human readable description for the release notes
- A picture of a cute animal (not mandatory but encouraged)