Airblader commented on pull request #17133: URL: https://github.com/apache/flink/pull/17133#issuecomment-929092061
> Because of that I'm worried that we'd just end up slapping @PublicEvolving on everything While I understand what you're getting at, this is a human problem that tooling cannot solve. We have code reviews and merging is limited to committers – we need to be able to trust that such "abuse" or carelessness doesn't happen, or address it if it does. Ultimately, we need to be able to change APIs, meaning there will always be a way to make the CI happy, and that also means there's always a way for people to "just do" something to bypass these tools. Tooling like this prevents changes to the API when they would happen accidentally / unknowingly. For a human it's essentially impossible to notice that a public API is returning an internal type somewhere down the line etc., and that's what the tooling can prevent. > but at the same time I could imagine this being very annoying overhead This is a bit besides the point, but I'd say that having to add JavaDocs to every public class is significantly more annoying since it requires actually writing custom text, even on test classes. --- A whole different approach that I know from other projects (not from the Java ecosystem, though) is generating a documentation of all public APIs in the CI and also versioning that separate from the code; if someone changes an API (be it accidentally or intentionally), the CI will fail. Having to update this file in the PR makes it impossible to not be aware of the change to the API you're doing. But even then it's the committer's job to review this change and ensure it is OK. -- 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: issues-unsubscr...@flink.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
