knight6236 commented on PR #10678: URL: https://github.com/apache/seatunnel/pull/10678#issuecomment-5292185615
@davidzollo @DanielLeens I've added caution-boxed documentation for `SEATUNNEL_CLASSLOADER_DEEP_CLEAN` (one in `docs/en`, one in `docs/zh`), matching the precedent shape of `engine-jar-storage-mode.md` and `rest-api-v1.md`. I want to be clear: I'm adding this out of respect for the community's convention, not because I find the technical arguments raised above fully persuasive. Two specific evidence points that were cited don't hold up under code inspection, and I think it's worth recording them so the reasoning stays on the record: **The WARN log is not a discovery channel.** The claim that the `WARN` log at `DefaultClassLoaderService.java:337-343` is "a bigger invitation than a docs page" because it "fires mid-failure and hands the operator two specific `--add-opens` flags" doesn't hold: that log only prints inside the `deepCleanEnabled=true` code path, on reflection failure. In other words, an operator only sees it *after* they have already opted in — it's a post-adoption troubleshooting signal, not a pre-adoption discovery path. The only pre-adoption discovery path is reading the source, and the inline comments there already carry the full set of caveats (Phase 1/3 framing, JDK 8 global-useCaches trade-off, both `--add-opens` flags). So the "informed docs paragraph vs. uninformed log message" comparison doesn't apply here. **The two cited precedents are a different category.** `connector-jar-storage-enable` and `rest-api.enabled` are `seatunnel.yaml` configuration items — user-facing deployment decisions. `SEATUNNEL_CLASSLOADER_DEEP_CLEAN` is a JVM `-D` system property. The category analogy isn't exact; a `-D` system property is closer to an internal escape hatch than to a deployment-mode switch. I'm raising these not to be stubborn — the docs have been added as requested. I'm raising them so that "the docs were added" isn't later read as implicit endorsement of those two arguments, and so that the precedent for future default-off `-D` system properties isn't set on a category-mismatched basis. The doc itself is intentionally minimal and uses the same `:::caution warn` framing as the two existing pages. Thanks again for the thorough discussion — it's given me a deeper appreciation for how this community collaborates. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
