From 35d0a6311417ef7944940798190129becbf652e7 Mon Sep 17 00:00:00 2001 From: Weidong Xu Date: Fri, 7 Nov 2025 10:53:44 +0800 Subject: [PATCH 1/4] 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/4] 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/4] 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/4] 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