[RLC] Support Versioning #2295

joheredi · 2024-02-17T18:54:00Z

This Pr introduces initial support for versioning in RLC and puts it under the experimental feature flag.

For now this generates N times where N is the number of versions in the spec, each RLC is put under a folder named after the version

src/
   v1/
   v2/
index.ts

It also generates a root level index.ts to export each version as a sub module, so customers can import it as:

import { v1 } from "@azure-rest/my-lib"

const client = v1.getClient();

Followup PRs will include exporting a "default" version in the root, and a later PR expand this support to Modular

qiaozha · 2024-02-18T01:37:39Z

Should we have a small review for versioning in rlc support, I remember our previous discussion about this is we should have each RLC package per each endpoint each version ? Personally, I am in favor of this approach to support versioning in RLC. :)

joheredi · 2024-02-18T04:42:30Z

Should we have a small review for versioning in rlc support, I remember our previous discussion about this is we should have each RLC package per each endpoint each version ? Personally, I am in favor of this approach to support versioning in RLC. :)

At some point before taking it out of the experimental flag, we definitely need a review. I was working closely with @bterlson on this and he is on board with the overall approach. I think we can go ahead implementing it and have a GA review once the implementation is completed for both RLC and Modular

qiaozha

I am thinking in the case that service team is deprecating an older api version, how do we express it in typespec ? will it be generated correctly to remove the older version code ?

qiaozha · 2024-02-18T07:17:24Z

packages/autorest.typescript/package.json

@@ -75,7 +75,7 @@
    "source-map-support": "^0.5.16",
    "ts-morph": "^15.1.0",
    "@azure/core-auth": "^1.6.0",
-    "@azure-tools/rlc-common": "workspace:^0.22.0"
+    "@azure-tools/rlc-common": "workspace:^0.23.0"


We should probably upgrade the version in packages/autorest.typescript/package.json too. and add the change log here to keep consistent.

you mean bump the version of autorest.typescript?

Pushed a change for this

qiaozha · 2024-02-18T07:20:33Z

packages/typespec-test/test/versioning/spec/tspconfig.yaml

+  "@azure-tools/typespec-ts":
+    azureSdkForJs: false
+    isModularLibrary: false
+    experimental: true


what should we generate if we don't pass experimental and the typespec is multi api version ?

I wonder if we should generate api version as client constructor parameter in that case?

I think we should generate the latest version if it's not experimental and the typespec is multi api version ? I remember previously, we had an issue that if an operation is removed in the latest version, we still generate this operation Azure/typespec-azure#129

For the scope of this PR we'll keep generating what we generate today. The superset of TypeSpec, with no regard to versioning. We should revisit this as we approach the completion of this feature

qiaozha · 2024-02-18T07:25:11Z

packages/typespec-test/test/versioning/generated/typespec-ts/src/index.ts

+import * as v1 from "./v1";
+import * as v2 from "./v2";


I wonder if we have considered use subpath export to support multiapi instead of using the sub namespaces?

Yeah, we should definetly do that for ESM. Maybe this for CJS and sub exports for ESM. I'll handle ESM in a follow up PR

qiaozha · 2024-02-18T07:30:01Z

packages/typespec-test/test/versioning/generated/typespec-ts/src/v1/demoServiceClient.ts

+): DemoServiceClient {
+  const baseUrl = options.baseUrl ?? `${endpoint}`;
+
+  const userAgentInfo = `azsdk-js-versioning-rest/1.0.0-beta.1`;


I think we are missing a logic to set default version for each single api version bits ?

This is a good question, not sure if we need to as this is client version not service version though

do you mean typespec api version is for client side not for service side ? Also, I am not quite sure what do you mean of service version ? currently, I think there's an ongoing task for deprecating @service.version here microsoft/typespec#2821 And our current implementation for api version has issues in both rlc and modular, I have a few fix in #2261 but would like to hold until the deprecation from typespec is finished.

What I mean is that user-agent is used to track the client version, not the service or API version. And, the client library version will be the same within the package.

Oh, I mean we missed a line like options.apiVersion = options.apiVersion ?? "v1"; above the userAgentInfo default prefix logic here. I just put the comment here, sorry for the misleading info.

Gotcha, okay yeah that makes sense now. Let me look into this

qiaozha · 2024-02-18T07:44:17Z

packages/typespec-test/test/versioning/generated/typespec-ts/src/v2/clientDefinitions.ts

+  (path: "/customGet"): CustomGet;
+}
+
+export type DemoServiceClient = Client & {


If we don't add suffix v2 to the client name, will it be confusing to our customer ?

I wouldn't like to alter the generated names. If a user just needs a single version which may be the most common scenario they won't really care to know if they are on DemoServiceClientv1 or v2 since they have already imported it.

import {v2} from "@azure-rest/foo" const client: v2.DemoServiceClient = ...

qiaozha · 2024-02-18T08:02:08Z

Also, I remember that Mike has pointed out, in the case of deprecating, service team still need to maintain the old version for about two years until it's retired, but client side like SDKs should stop releasing the SDK to include the apis that are deprecated. And typespec is representing both service side and client side if I understand correctly ?

joheredi · 2024-02-20T01:11:05Z

Also, I remember that Mike has pointed out, in the case of deprecating, service team still need to maintain the old version for about two years until it's retired, but client side like SDKs should stop releasing the SDK to include the apis that are deprecated. And typespec is representing both service side and client side if I understand correctly ?

I think at that point the service team would remove the deprecated version from the spec. That doesn't mean they stop servicing, they can still maintain the service version, just that any new code gen won't include the deprecated version(s). @bterlson to confirm.

microsoft-github-policy-service · 2024-04-26T05:10:54Z

Hi @joheredi. Thank you for your interest in helping to improve the Azure SDK experience and for your contribution. We've noticed that there hasn't been recent engagement on this pull request. If this is still an active work stream, please let us know by pushing some changes or leaving a comment. Otherwise, we'll close this out in 7 days.

microsoft-github-policy-service · 2024-05-06T02:10:18Z

Hi @joheredi. Thank you for your contribution. Since there hasn't been recent engagement, we're going to close this out. Feel free to respond with a comment containing "/reopen" if you'd like to continue working on these changes. Please be sure to use the command to reopen or remove the "no-recent-activity" label; otherwise, this is likely to be closed again with the next cleanup pass.

joheredi added 4 commits February 16, 2024 09:21

Generate Specific version

1e2abde

Generate all versions

810994d

Generate versioned RLC

704430f

Update version and changelog

bc5a488

joheredi requested review from sarangan12, qiaozha and MaryGao as code owners February 17, 2024 18:54

joheredi added 2 commits February 17, 2024 10:55

update changelog

a8d597c

Update deps

e5c31ac

fix unit test

5dd125e

qiaozha reviewed Feb 18, 2024

View reviewed changes

Temporarly depend on rlc-common alpha

6e03b06

microsoft-github-policy-service bot added the no-recent-activity There has been no recent activity on this issue. label Apr 26, 2024

microsoft-github-policy-service bot closed this May 6, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[RLC] Support Versioning #2295

[RLC] Support Versioning #2295

joheredi commented Feb 17, 2024

qiaozha commented Feb 18, 2024

joheredi commented Feb 18, 2024

qiaozha left a comment

qiaozha Feb 18, 2024

joheredi Feb 20, 2024

joheredi Feb 20, 2024

qiaozha Feb 18, 2024

qiaozha Feb 18, 2024

qiaozha Feb 18, 2024

joheredi Feb 18, 2024

qiaozha Feb 18, 2024

joheredi Feb 18, 2024

qiaozha Feb 18, 2024

joheredi Feb 18, 2024

qiaozha Feb 19, 2024

joheredi Feb 19, 2024

qiaozha Feb 20, 2024

joheredi Feb 20, 2024

qiaozha Feb 18, 2024

joheredi Feb 20, 2024

qiaozha commented Feb 18, 2024

joheredi commented Feb 20, 2024

microsoft-github-policy-service bot commented Apr 26, 2024

microsoft-github-policy-service bot commented May 6, 2024

[RLC] Support Versioning #2295

[RLC] Support Versioning #2295

Conversation

joheredi commented Feb 17, 2024

qiaozha commented Feb 18, 2024

joheredi commented Feb 18, 2024

qiaozha left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

qiaozha commented Feb 18, 2024

joheredi commented Feb 20, 2024

microsoft-github-policy-service bot commented Apr 26, 2024

microsoft-github-policy-service bot commented May 6, 2024