From 35d0a6311417ef7944940798190129becbf652e7 Mon Sep 17 00:00:00 2001 From: Weidong Xu Date: Fri, 7 Nov 2025 10:53:44 +0800 Subject: [PATCH 1/9] prompt: migrate copilot-instructions.md to AGENTS.md --- AGENTS.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..6f34b3445b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,29 @@ +# Update Node.JS Package for Latest Dependencies + +Instructions: +* Always use absolute path when change directory. + +Steps: + +1. In "core" folder, run `git pull upstream main` to fetch latest commit from upstream or origin. +2. Go back to project root. Commit the change in "core" folder. +3. Run `ncu -u` on "package.json" in both "package.json" from "typespec-extension" and "typespec-tests" folder. +4. Update package versions in `peerDependencies` (keep the semver range) in "package.json" from "typespec-extension" folder, according to the corresponding package versions in `devDependencies`. +5. Update package versions in `override` (keep the semver range) in "package.json" from "typespec-tests" folder, according to the corresponding package versions in "package.json" from "typespec-extension" folder. +6. Save the files, and run `npm install` in "typespec-extension" folder, so that "package-lock.json" would be updated. +7. Commit the changes in "typespec-extension" and "typespec-tests" folders. +8. Run `pwsh SyncTests.ps1` in "typespec-tests" folder. +9. Commit the changes in "typespec-tests" folder, include new files. + +# Prepare for Minor/Patch Release + +Steps: + +1. Bump minor/patch version of `@typespec/typespec-java` in both "package.json" from "typespec-extension" and "typespec-tests" folder. +2. Save the file, and run `npm install` in "typespec-extension" folder, so that "package-lock.json" would be updated. +3. Add a new item in release history in "typespec-extension/changelog.md". The version would be the minor/patch version. The date would be today. + +The [publish to NPM pipeline](https://dev.azure.com/azure-sdk/internal/_build?definitionId=5618) need to be triggered, after the PR is merged. + +After release, the [sync SDK pipeline](https://dev.azure.com/azure-sdk/internal/_build?definitionId=6270) need to be triggered, to sync the released typespec-java into the SDK repository. +This pipeline also regenerates all SDK based on TypeSpec. From 9e4b16716ca33f14193bf5f1bae971416498fdbe Mon Sep 17 00:00:00 2001 From: Weidong Xu Date: Fri, 7 Nov 2025 10:54:27 +0800 Subject: [PATCH 2/9] remove copilot-instructions --- .github/copilot-instructions.md | 29 ----------------------------- 1 file changed, 29 deletions(-) delete mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md deleted file mode 100644 index 6f34b3445b..0000000000 --- a/.github/copilot-instructions.md +++ /dev/null @@ -1,29 +0,0 @@ -# Update Node.JS Package for Latest Dependencies - -Instructions: -* Always use absolute path when change directory. - -Steps: - -1. In "core" folder, run `git pull upstream main` to fetch latest commit from upstream or origin. -2. Go back to project root. Commit the change in "core" folder. -3. Run `ncu -u` on "package.json" in both "package.json" from "typespec-extension" and "typespec-tests" folder. -4. Update package versions in `peerDependencies` (keep the semver range) in "package.json" from "typespec-extension" folder, according to the corresponding package versions in `devDependencies`. -5. Update package versions in `override` (keep the semver range) in "package.json" from "typespec-tests" folder, according to the corresponding package versions in "package.json" from "typespec-extension" folder. -6. Save the files, and run `npm install` in "typespec-extension" folder, so that "package-lock.json" would be updated. -7. Commit the changes in "typespec-extension" and "typespec-tests" folders. -8. Run `pwsh SyncTests.ps1` in "typespec-tests" folder. -9. Commit the changes in "typespec-tests" folder, include new files. - -# Prepare for Minor/Patch Release - -Steps: - -1. Bump minor/patch version of `@typespec/typespec-java` in both "package.json" from "typespec-extension" and "typespec-tests" folder. -2. Save the file, and run `npm install` in "typespec-extension" folder, so that "package-lock.json" would be updated. -3. Add a new item in release history in "typespec-extension/changelog.md". The version would be the minor/patch version. The date would be today. - -The [publish to NPM pipeline](https://dev.azure.com/azure-sdk/internal/_build?definitionId=5618) need to be triggered, after the PR is merged. - -After release, the [sync SDK pipeline](https://dev.azure.com/azure-sdk/internal/_build?definitionId=6270) need to be triggered, to sync the released typespec-java into the SDK repository. -This pipeline also regenerates all SDK based on TypeSpec. From 680b6779d33cb0a015ef8f7f3f75cc844d17787f Mon Sep 17 00:00:00 2001 From: Weidong Xu Date: Fri, 7 Nov 2025 11:50:54 +0800 Subject: [PATCH 3/9] some instruction for dev --- AGENTS.md | 18 +++++++++++++++--- docs/developer/typespec/readme.md | 2 ++ 2 files changed, 17 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6f34b3445b..172ae42cf5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,19 @@ -# Update Node.JS Package for Latest Dependencies +# Development + +See [Developer Guide for TypeSpec Emitter](docs/developer/typespec/readme.md) for basics. + +Guideline: + +- Most of the development work should happen in "core/packages/http-client-java" folder. +- Before start the development in "core" folder, always checkout latest code from main branch, and create a dev branch upon it. +- When check-in code in "core" folder, do not check-in the files in "core.patch". + +# Update and Release + +## Update Node.JS Package for Latest Dependencies Instructions: -* Always use absolute path when change directory. +- Always use absolute path when change directory. Steps: @@ -15,7 +27,7 @@ Steps: 8. Run `pwsh SyncTests.ps1` in "typespec-tests" folder. 9. Commit the changes in "typespec-tests" folder, include new files. -# Prepare for Minor/Patch Release +## Prepare for Minor/Patch Release Steps: diff --git a/docs/developer/typespec/readme.md b/docs/developer/typespec/readme.md index a7e4c20836..beab611d6c 100644 --- a/docs/developer/typespec/readme.md +++ b/docs/developer/typespec/readme.md @@ -8,6 +8,8 @@ As [NPM package](https://www.npmjs.com/package/@azure-tools/typespec-java), it i At present, almost all the code of the emitter is in [microsoft/typespec repository](https://github.com/microsoft/typespec/tree/main/packages/http-client-java). +This repository is checked out at `core` folder as submodule. + ### Build NPM package is in `typespec-extension` folder. From c53ec9668de500083739f1dd4fcbefd20f8e0fad Mon Sep 17 00:00:00 2001 From: Weidong Xu Date: Fri, 7 Nov 2025 16:36:46 +0800 Subject: [PATCH 4/9] more doc --- AGENTS.md | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 172ae42cf5..6821fd7574 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,12 +1,43 @@ # Development -See [Developer Guide for TypeSpec Emitter](docs/developer/typespec/readme.md) for basics. +The emitter is the [TypeSpec](https://typespec.io/) library for emitting Java client from the TypeSpec REST protocol binding. + +See [Emitter](https://typespec.io/docs/extending-typespec/emitters-basics/) for the basics on the TypeSpec emitter library. + +See [Developer Guide for TypeSpec Emitter](docs/developer/typespec/readme.md) for basics on this repostority. Guideline: - Most of the development work should happen in "core/packages/http-client-java" folder. - Before start the development in "core" folder, always checkout latest code from main branch, and create a dev branch upon it. - When check-in code in "core" folder, do not check-in the files in "core.patch". +- When prepare the PR, create 2 PRs, one for the code changes in submodule ("typespec" repository, if there is change), one for the code changes in this repository (which would include the update on "core" submodule). + +## TypeScript Part for the Emitter + +TypeScript code for the Emitter is in "core/packages/http-client-java/emitter" folder. Follow the package.json for the build and unit test. + +The code there, in runtime, produces a "code-model.yaml" file, and passes it to Java Part to generate Java client. + +## Java Part for the Emitter + +Java code for the Emitter is in "core/packages/http-client-java/generator/http-client-generator" (which depends on "http-client-generator-core" and "http-client-generator-mgmt" module). Follow the pom.xml for the build and unit test. + +The code there, in runtime, consumes the "code-model.yaml" file produced by the TypeSpec Part, and generate the Java client. + +## End-to-end test with TypeSpec + +The end-to-end takes a TypeSpec file, and produce a Java client. +We'd like to see whether the TypeSpec file (with a certain feature) can produce expected Java code. + +The test happens in "core/packages/http-client-java/generator/http-client-generator-test" folder. + +If there is code change in "core", before running any end-to-end test, first run the "Setup.ps1" script there, to update the test environment. + +When calling "tsp compile", always set `--config .`. + +The Java client would be generated in its "tsp-output" folder. +When running a new test, delete this folder if exists. # Update and Release From 361d666328f25b63682815e70c98519f5373e0ef Mon Sep 17 00:00:00 2001 From: Weidong Xu Date: Wed, 4 Feb 2026 11:15:24 +0800 Subject: [PATCH 5/9] spelling --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6821fd7574..b459f821e7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ The emitter is the [TypeSpec](https://typespec.io/) library for emitting Java cl See [Emitter](https://typespec.io/docs/extending-typespec/emitters-basics/) for the basics on the TypeSpec emitter library. -See [Developer Guide for TypeSpec Emitter](docs/developer/typespec/readme.md) for basics on this repostority. +See [Developer Guide for TypeSpec Emitter](docs/developer/typespec/readme.md) for basics on this repository. Guideline: @@ -41,7 +41,7 @@ When running a new test, delete this folder if exists. # Update and Release -## Update Node.JS Package for Latest Dependencies +## Update Node.js Package for Latest Dependencies Instructions: - Always use absolute path when change directory. From 74c9a723f1db1c2cddfd2e60b2349f8fde79fb57 Mon Sep 17 00:00:00 2001 From: Weidong Xu Date: Wed, 4 Feb 2026 11:31:16 +0800 Subject: [PATCH 6/9] add skill to build from dev --- .github/skills/validate-dev-build/SKILL.md | 37 ++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 .github/skills/validate-dev-build/SKILL.md diff --git a/.github/skills/validate-dev-build/SKILL.md b/.github/skills/validate-dev-build/SKILL.md new file mode 100644 index 0000000000..8b4f0c4d64 --- /dev/null +++ b/.github/skills/validate-dev-build/SKILL.md @@ -0,0 +1,37 @@ +--- +name: validate-dev-build +description: Build the emitter with dev dependencies, and validate end-to-end tests +argument-hint: [test-case] +--- + +## Update Node.js dependencies to dev + +Read "typespec-extension/package.json", if it does not depends on a dev version of `@typespec/compiler` (e.g. `X-dev.Y`), run following command on repository root: + +``` +npx -y @azure-tools/typespec-bump-deps typespec-extension/package.json typespec-tests/package.json --add-npm-overrides +``` + +## Prepare end-to-end test environment + +Under "typespec-tests" folder, run `Setup.ps1`. + +## Generate end-to-end test code + +Under "typespec-tests" folder. + +`[test-case]` usually in the form of an URL, e.g. "https://github.com/Azure/typespec-azure/tree/main/packages/azure-http-specs/specs/azure/client-generator-core/override" + +Map this URL to the location of the test case in "node_modules". +E.g. above would map to "node_modules/@azure-tools/azure-http-specs/specs/azure/client-generator-core/override/client.tsp" + +URL "https://github.com/microsoft/typespec/tree/main/packages/http-specs/specs/encode/array" would map to "node_modules/@typespec/http-specs/specs/encode/array/main.tsp" + +- Use "client.tsp" when available. Otherwise, use "main.tsp". +- Escape the `@`, if it is necessary to do so in terminal. + +Run +``` +tsp compile --config . [location-of-test-case] +``` +to generate Java code. From 76f312557e90e24f66145bec1c5926a608974cb3 Mon Sep 17 00:00:00 2001 From: Weidong Xu Date: Wed, 4 Feb 2026 11:40:06 +0800 Subject: [PATCH 7/9] add skill to use dev typespec dependencies --- .github/skills/validate-dev-build/SKILL.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/skills/validate-dev-build/SKILL.md b/.github/skills/validate-dev-build/SKILL.md index 8b4f0c4d64..61b6cba2be 100644 --- a/.github/skills/validate-dev-build/SKILL.md +++ b/.github/skills/validate-dev-build/SKILL.md @@ -7,11 +7,12 @@ argument-hint: [test-case] ## Update Node.js dependencies to dev Read "typespec-extension/package.json", if it does not depends on a dev version of `@typespec/compiler` (e.g. `X-dev.Y`), run following command on repository root: - ``` npx -y @azure-tools/typespec-bump-deps typespec-extension/package.json typespec-tests/package.json --add-npm-overrides ``` +Under "typespec-extension" folder, run `npm install --force` to install the dev dependencies. + ## Prepare end-to-end test environment Under "typespec-tests" folder, run `Setup.ps1`. From 0321cd962b19c3d76b3e8fb7e174b89a21134f23 Mon Sep 17 00:00:00 2001 From: Weidong Xu Date: Wed, 4 Feb 2026 12:48:37 +0800 Subject: [PATCH 8/9] spellcheck --- AGENTS.md | 12 ++++++------ readme.md | 4 ++-- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b459f821e7..4d7aaa08a9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,9 +9,9 @@ See [Developer Guide for TypeSpec Emitter](docs/developer/typespec/readme.md) fo Guideline: - Most of the development work should happen in "core/packages/http-client-java" folder. -- Before start the development in "core" folder, always checkout latest code from main branch, and create a dev branch upon it. -- When check-in code in "core" folder, do not check-in the files in "core.patch". -- When prepare the PR, create 2 PRs, one for the code changes in submodule ("typespec" repository, if there is change), one for the code changes in this repository (which would include the update on "core" submodule). +- Before starting the development in "core" folder, always checkout latest code from main branch, and create a dev branch upon it. +- When checking in code in "core" folder, do not check-in the files in "core.patch". +- When preparing the PR, create 2 PRs, one for the code changes in submodule ("typespec" repository, if there is change), one for the code changes in this repository (which would include the update on "core" submodule). ## TypeScript Part for the Emitter @@ -27,7 +27,7 @@ The code there, in runtime, consumes the "code-model.yaml" file produced by the ## End-to-end test with TypeSpec -The end-to-end takes a TypeSpec file, and produce a Java client. +The end-to-end takes a TypeSpec file, and produces a Java client. We'd like to see whether the TypeSpec file (with a certain feature) can produce expected Java code. The test happens in "core/packages/http-client-java/generator/http-client-generator-test" folder. @@ -66,7 +66,7 @@ Steps: 2. Save the file, and run `npm install` in "typespec-extension" folder, so that "package-lock.json" would be updated. 3. Add a new item in release history in "typespec-extension/changelog.md". The version would be the minor/patch version. The date would be today. -The [publish to NPM pipeline](https://dev.azure.com/azure-sdk/internal/_build?definitionId=5618) need to be triggered, after the PR is merged. +The [publish to NPM pipeline](https://dev.azure.com/azure-sdk/internal/_build?definitionId=5618) needs to be triggered, after the PR is merged. -After release, the [sync SDK pipeline](https://dev.azure.com/azure-sdk/internal/_build?definitionId=6270) need to be triggered, to sync the released typespec-java into the SDK repository. +After release, the [sync SDK pipeline](https://dev.azure.com/azure-sdk/internal/_build?definitionId=6270) needs to be triggered, to sync the released typespec-java into the SDK repository. This pipeline also regenerates all SDK based on TypeSpec. diff --git a/readme.md b/readme.md index f29af092c9..b408664308 100644 --- a/readme.md +++ b/readme.md @@ -15,7 +15,7 @@ npm install -g autorest ``` # Usage -To use the latest released preview(https://github.com/Azure/autorest.java/releases), run +To use the latest released preview (https://github.com/Azure/autorest.java/releases), run ```bash autorest --java --use:@autorest/java@4.x.x @@ -45,7 +45,7 @@ autorest --java Java files will be generated under `where/to/generate/java/files/src/main/java/specified/java/package`. -To debug, add `--java.debugger` to the argument list. The JVM will suspend at the beginning of the execution. Then attach a remote debugger in your IDE to `localhost:5005`. **Make sure you detach the debugger before killing the AutoRest process. Otherwise it will fail to shutdown the JVM and leave it orphaned. (which can be killed in the Task Manager)** +To debug, add `--java.debugger` to the argument list. The JVM will suspend at the beginning of the execution. Then attach a remote debugger in your IDE to `localhost:5005`. **Make sure you detach the debugger before killing the AutoRest process. Otherwise it will fail to shut down the JVM and leave it orphaned. (which can be killed in the Task Manager)** # Recommended Settings From ed255ffeb643b5f73b251b70b84196c35799eb7a Mon Sep 17 00:00:00 2001 From: Weidong Xu Date: Wed, 4 Feb 2026 12:50:04 +0800 Subject: [PATCH 9/9] remove the e2e part in AGENTS --- AGENTS.md | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4d7aaa08a9..30dfe61a8a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,20 +25,6 @@ Java code for the Emitter is in "core/packages/http-client-java/generator/http-c The code there, in runtime, consumes the "code-model.yaml" file produced by the TypeSpec Part, and generate the Java client. -## End-to-end test with TypeSpec - -The end-to-end takes a TypeSpec file, and produces a Java client. -We'd like to see whether the TypeSpec file (with a certain feature) can produce expected Java code. - -The test happens in "core/packages/http-client-java/generator/http-client-generator-test" folder. - -If there is code change in "core", before running any end-to-end test, first run the "Setup.ps1" script there, to update the test environment. - -When calling "tsp compile", always set `--config .`. - -The Java client would be generated in its "tsp-output" folder. -When running a new test, delete this folder if exists. - # Update and Release ## Update Node.js Package for Latest Dependencies