I think there are three questions to be anwsered, and here are my two cents.
1) How do we define the compatibility guarantees for cli interfaces? I'd be +1 for reusing the existing @Public and @PublicEvolving annotations, as suggested by Ferenc. Having multiple sets of rules in the same project may easily confuse users. 2) What deprecation process is required for cli interfaces? If we are reusing the existing annotations, I think we'd better to have the same deprecation process as well, for the same reason not to confuse users. 3) How do we make user aware of the compatibility guarantees and deprecations of cli interfaces? I think there are several things that we can do. - In addition to codes and JavaDocs, we should also display the annotations (Public / PublicEvolving / Experimental Dprecated) in documentation [1] and cli helps (things you see when execute `<FLINK_HOME>/bin/flink -h`). - Print a warning message if a deprecated command / argument is used, as suggested by Muhammet. - We can also provide a strict / compatible mode. E.g., we use strict mode by default, which fails if any deprecated interface is used. In the error message, we hint user that he/she can manually enable the compatible mode, which allows deprecated interfaces. This should draw users' attention to the deprecation of the interfaces, while not block the adoption of a new Flink version with breaking changes. There are probably more details to be considered, e.g., should we fail immediately once an interface is deprecated in strict mode, how long do we support a deprecated interface in compatible mode, how to properly suggest users about the compatible mode while not encourage them to always stay in that mode, etc. Best, Xintong [1] https://nightlies.apache.org/flink/flink-docs-master/docs/deployment/cli/ On Mon, Jul 8, 2024 at 5:54 PM Muhammet Orazov <mor+fl...@morazow.com.invalid> wrote: > Hey Ferenc, > > Yes correct. My thoughts were based on finding tradeoff between > following fully deprecation process and leaner one for CLIs. > > Since cli are not like APIs, I think users would be aware of > deprecation only when were remove the commands. That is they > try to run their jobs with upgrade and it fails with action > not available. > > So maybe we don't have to follow fully API `@PublicEvolving` > process for this. > > Another maybe user friendly approach would be to inform with > warning that the `run-application` cli action will be dropped, > and suggest new action and migration on the log message. > > Best, > Muhammet > > On 2024-07-04 20:17, Ferenc Csaky wrote: > > Hi Muhammet, > > > > Thank you for your thoughts! > > > >> After two minor releases, and on next major version bump, > >> we could drop the `run-application` method as suggested > >> on discussion by Xintong. > > > > Here, you describe the deprecation/removal process of a public > > API by the definition we have in the project now. So if the same > > applies to a CLI action, why should we not enforce such behavior > > for those as well? > > > > If following the same process for CLIs make sense, we should also > > enforce the same compatibility guarantees IMO. > > > > Best, > > Ferenc > > > > > > > > On Friday, 28 June 2024 at 09:30, Muhammet Orazov > > <mor+fl...@morazow.com.INVALID> wrote: > > > >> > >> > >> Hey Ferenc, > >> > >> Thanks for starting the discussion! > >> > >> I agree that the CLI is user facing, but I think we don't > >> have to treat it as other public APIs. > >> > >> I'd propose to throw user friendly exception for > >> `run-application` with suggestion to use `run` case instead. > >> This would make users aware of the change and require them > >> to migrate their scripts. > >> > >> After two minor releases, and on next major version bump, > >> we could drop the `run-application` method as suggested > >> on discussion by Xintong. > >> > >> Best, > >> Muhammet > >> > >> > >> On 2024-06-26 15:33, Ferenc Csaky wrote: > >> > >> > Hello devs, > >> > I would like to open a discussion about considerations regarding how > to > >> > deprecate CLI > >> > actions, and what compatibility guarantees should apply to such cases. > >> > The topic came up in > >> > a previous discussion [1] about a current FLIP to merge the run and > >> > run-application > >> > behavior [2]. > >> > > >> > According to Xintong's previous inputs, currently the Flink CLI, or > its > >> > actions are not handled > >> > as public APIs by the existing definition (@Public or @PublicEvolving > >> > annotated). So > >> > legally it would be possible to change CLIs anytime. I agree with > >> > Xintong that CLI actions > >> > should be considered as public APIs, and as such, compatibility > >> > guarantees should be > >> > provided. > >> > > >> > CLI actions are defined as private constants in CliFrontend [3], so > >> > IMO the existing rules > >> > are not perfectly applicable as is. Both @Public and @PublicEvolving > >> > can be applied to > >> > fields (although for @Public that is only true as per the javadoc, > >> > technically it can only be > >> > applied to classes), so I think that could be a good approach that is > >> > achievable with minimal > >> > effort and changes. > >> > > >> > It would also be possible to define a different process, but IMO the > >> > more lightweight and > >> > maintainable the process the better, so it is a good thing if it is > not > >> > necessary to bring in > >> > new entities and/or rules to check and enforce compatibility. > >> > > >> > WDYT? > >> > > >> > Best, > >> > Ferenc > >> > > >> > [1] https://lists.apache.org/thread/0vc8v3t7fr6w9hmwf9zbjbyk5c3bcj50 > >> > [2] > >> > > https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=311626179 > >> > [3] > >> > > https://github.com/apache/flink/blob/27287a105f6585e89795e2a6cbffa8254abb6e57/flink-clients/src/main/java/org/apache/flink/client/cli/CliFrontend.java#L98 >
