Rename "language" to "generator-name" in cli and maven-plugin #39
Comments
|
I agree with supporting both but showing a deprecation message on language. I would suggest erroring if both are set to avoid potential issues. I'd also suggest clearly defining the removal timeline (maybe by version 3.1). Additionally, while we deprecate the language option, we could also provide a mapping of the generator renames. This would allow users to almost seamlessly upgrade, and the CLI would notify of the necessary changes for subsequent releases. |
|
And to the split of options, I fully agree with this. I haven't yet made such a change, because I'd consider this too much of a breaking change to include in the 3.0.0 release. We'll probably want to target this for 4.0.0. |
|
Thank you for this feedback, I like all theses suggestions. One might be more complicated:
I am not sure if we have a release roadmap/timeline by now... |
|
Even without a roadmap, I think we can explicitly say "we will remove this in the next minor release". I think my use of "timeline" to refer to the minor release was confusing. My point was that we shouldn't randomly remove it in a build revision (e.g. 3.0.22), as things like this catch people off guard. |
|
Oh, I see what you were saying about removing language. If we were to move to It's likely that we'd want to go through a full major release with |
The language option (--lang and -l in CLI, language in maven plugin) has drifted from the original intention of defining a top-level language implementation with variance on library. Generators began to encode generator type into language (e.g. erlang-client), reused language as framework-only (e.g. scalatra), or embedded language and framework (e.g. typescript-angular). With the 3.0.0 release of openapi-generator, we've moved to a standardization of these names, which means they no longer fit into the singular concept of a "language". We've discussed plans to provide a better user experience around the CLI, breaking apart the generator lookup into the variations that make up a generator: * language * type * framework * version? To do this, we must first deprecate language and warn users that what they're currently using (e.g. scalatra, typescript-angular) is being replaced by generatorName and that language may mean something else in a later version of the generator. For discussion, see OpenAPITools#39.
|
@jmini I've opened #57 with the intro of generator-name and deprecation of 'language' as a CLI and Maven Plugin option. I think this is a code quality thing that should make it into the 3.0.0 release so that the deprecation can exist for an entire major release. I've just thought of a question about the implementation. I'll add it there. |
|
Thank you a lot for opening the PR, and yes it should be part of our first 3.0.0 release. |
|
No I think we should close this one as solved with version |
Signed-off-by: aserkes <[email protected]>
On the long term we might want to offer an other way to select the targeted generator.
Probably with multiple switches (to be defined more precisely):
Examples:
A first move that we could do now with our first release is to rename the term “language” with “generator-name“ in the maven Plugin and in the CLI.
We might support them both options for backward compatibility, but with a warning explaining that “generator-name“ should be preferred.
What are the opinions?
cc: @jimschubert
The text was updated successfully, but these errors were encountered: