[Discussion] SDK emitters, emitter options for package name/version

[weidongxu-microsoft]

Context

• Package information (like package name/version) typically appear in package config file (e.g. pom.xml in Java, setup.py in Python, .csproj in .NET)
• Though it could also appear in code, e.g. code setting the "UserAgent" header.
• For Azure SDK, the package-name typically follows a pattern, and it may not need to be specified for typespec (e.g. it may be inferred from namespace)

For Azure, current options are

• Java, none
• .NET, library-name
• Python, package-name
• JS, packageDetails with property name, version, description (this option also applies to unbranded)
  https://github.com/microsoft/typespec/blob/469c96a00df3a37b1f0c51c729647b1f47735a85/website/src/content/docs/docs/emitters/sdk-clients/introduction.md#packagedetails

Question

Do we want to have consistent emitter options for this package information?

If we don't want to do this, we can tell user that "emitter generate the package config file, feel free to modify it as you see fit".
But this won't work for the info in code (if there is such code).

Candidate options, if we want to have a consistent emitter options

If we do a consistent solution, maybe we do like JS (however, typical emitter option is kebab casing, e.g. package-details).

One advantage is that emitter can have slightly different sub property. E.g. Java would use a group-id for the config of Maven "groupId".

  package-details:
    group-id: ..
    name: ..
    version: ..

Note that there be a current limitation on typespec compiler, that command line --option does not work on the sub property e.g. "@typespec/http-client-javascript.packageDetails.name=<name>"

[lmazuel]

We just talked about it today in meeting:

• We should try to be consistent
• But *only if the concept applies to that language`. For instance, we don't want to force Java to give up on group id / artifcat id, if those terms are better for Java

We didn't discuss what exact syntax to use. Should we group under package-details? Why not? Should we have individual options? Why not? :). I feel this should be discussed, but eventually, when we will go in the Client emitter pages, we should thrive to have a common flags section for ease of usage by customers.

[m-nash]

I don't think we should have things like version defined in tspconfig.yaml since most of us have language idiomatic ways to control sdk version that would supersede this.

[weidongxu-microsoft]

For Azure, in some languages, the version could appear in code (e.g. as value in UserAgent header). Though there is certain language specific way for reading it from project configure (e.g. Java may read it from a properties file with key-value version=${project.version}) so that it does not to generated as code.

@MaryGao about JS.

Even if we don't have version in code, the version would be in project file.
We may provide a stub and say "feel free to modify the project file, to update the version" to dev.

[markcowl]

@raych1 FYI

[MaryGao]

One thing to discuss is if we'd like to define the subset or superset options cross emitters? For example currently there is package-name for Java, but we have that config for other languages, if we have consistent package-name emitter option, will all language adopt that flag or Java would simply ignore that config?

In JS package version is used both in code and config file. In Azure it is an optional configuration because we have tool to control version bumping. And we also expose this flag to customers to customize their own versions if they want in Azure and unbranded.