From 659f6326b37d9b3e5a0d4addf1cc1df6e110c893 Mon Sep 17 00:00:00 2001 From: "Xiaofei Cao (from Dev Box)" Date: Mon, 20 Jul 2026 17:12:12 +0800 Subject: [PATCH 1/3] docs(typespec-java): document patch release process in CONTRIBUTING --- packages/typespec-java/CONTRIBUTING.md | 70 +++++++++++++++++++++++++- 1 file changed, 69 insertions(+), 1 deletion(-) diff --git a/packages/typespec-java/CONTRIBUTING.md b/packages/typespec-java/CONTRIBUTING.md index 0eb1f72a60..1fcb55d9e2 100644 --- a/packages/typespec-java/CONTRIBUTING.md +++ b/packages/typespec-java/CONTRIBUTING.md @@ -87,7 +87,75 @@ Make sure to run the following commands: ## Release Process -TODO: The post-release process for `@azure-tools/typespec-java` has not been finalized yet. +This describes how to ship a patch (hotfix) release of `@azure-tools/typespec-java` from a +`release/*` branch. + +### 1. Create the release branch and bump the version + +The overall publishing background for this repo is documented in the root +[`CONTRIBUTING.md` "Publishing" section](../../CONTRIBUTING.md#publishing) (the monthly +TypeSpec-Azure release flow). For preparing the branch and bumping this package's version +specifically, follow the [`hotfix-release` skill](../../.github/skills/hotfix-release/SKILL.md), +which walks through creating the `publish/hotfix/-` branch off the +`release/` branch and running `pnpm chronus version --ignore-policies`. + +### 2. Pin the core commit for the patch (`core-commit.json`) + +Release branches do not carry `core/` submodule updates, so bump the pin instead of the +submodule. Update the `sha` field in [`core-commit.json`](./core-commit.json) to the target +upstream `core` commit you want this patch to build and generate from. `Build-Generator.ps1` / +`Copy-Sources.ps1` (build) and `SyncTests.ps1` transiently check out that pinned commit — when it +is newer than the branch's submodule checkout — and always restore the submodule afterwards, so +the patch picks up the core changes without moving the submodule pointer. + +### 3. Sync tests from core + +Run the test sync from `packages/typespec-java/emitter-tests`: + +```powershell +pwsh ./SyncTests.ps1 +``` + +This copies the hand-written tests (`src`) and TypeSpec specs (`tsp`) from +`http-client-generator-test` in the pinned `core/` commit, syncs shared dependency/override +versions, and updates `emitter-tests/package.json` — both its own `version` and the +`file:../azure-tools-typespec-java-.tgz` dependency — to align with the new emitter +version from `package.json`. Commit any resulting changes. + +### 4. Open the PR against the release branch + +Open a PR targeting `release/` (not `main`). + +### 5. (Optional) Validate SDK regeneration from the PR emitter (before merging) + +Optionally, before merging, use the +[`typespec-java - sync sdk`](https://dev.azure.com/azure-sdk/internal/_build?definitionId=8274&_a=summary) +pipeline to regenerate the Azure SDKs from the emitter built out of this PR: + +- Leave **Emitter Version** as `none` (builds the emitter from source). +- Set **PR Id or Branch** to this PR's ID. + +This produces an SDK PR generated from the PR's emitter so you can validate the regeneration +before the emitter is released. + +### 6. Merge and auto-publish + +After the PR is merged, the emitter is automatically released by the +[`typespec-azure - Publish`](https://dev.azure.com/azure-sdk/internal/_build?definitionId=1793) +pipeline. + +### 7. Backmerge to main + +Merging into the release branch creates a backmerge branch +(`backmerge/release/-`). Open a PR from that branch targeting `main` and merge it so +the version bump and changelog are reflected in `main`. + +### 8. Regenerate and merge the SDK PR with the released version + +Finally, run the +[`typespec-java - sync sdk`](https://dev.azure.com/azure-sdk/internal/_build?definitionId=8274&_a=summary) +pipeline again, this time with **Emitter Version** set to the released `@azure-tools/typespec-java` +version (leaving PR Id or Branch as `none`). Review and merge the resulting SDK PR. ## Trademarks From 493a4581270a94cfb028c127f9dae4c56114c665 Mon Sep 17 00:00:00 2001 From: "Xiaofei Cao (from Dev Box)" Date: Mon, 20 Jul 2026 17:14:11 +0800 Subject: [PATCH 2/3] docs(typespec-java): mark final SDK regen step as optional --- packages/typespec-java/CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/typespec-java/CONTRIBUTING.md b/packages/typespec-java/CONTRIBUTING.md index 1fcb55d9e2..2dca5ec3f8 100644 --- a/packages/typespec-java/CONTRIBUTING.md +++ b/packages/typespec-java/CONTRIBUTING.md @@ -150,9 +150,9 @@ Merging into the release branch creates a backmerge branch (`backmerge/release/-`). Open a PR from that branch targeting `main` and merge it so the version bump and changelog are reflected in `main`. -### 8. Regenerate and merge the SDK PR with the released version +### 8. (Optional) Regenerate and merge the SDK PR with the released version -Finally, run the +Optionally, run the [`typespec-java - sync sdk`](https://dev.azure.com/azure-sdk/internal/_build?definitionId=8274&_a=summary) pipeline again, this time with **Emitter Version** set to the released `@azure-tools/typespec-java` version (leaving PR Id or Branch as `none`). Review and merge the resulting SDK PR. From 7f0b2bc3c64c878cd989330724bb2c30ea83c1e5 Mon Sep 17 00:00:00 2001 From: "Xiaofei Cao (from Dev Box)" Date: Wed, 22 Jul 2026 13:44:18 +0800 Subject: [PATCH 3/3] docs(typespec-java): restructure release process into sync + release PRs --- packages/typespec-java/CONTRIBUTING.md | 112 ++++++++++--------------- 1 file changed, 43 insertions(+), 69 deletions(-) diff --git a/packages/typespec-java/CONTRIBUTING.md b/packages/typespec-java/CONTRIBUTING.md index 0ec0f1097c..2d8808362f 100644 --- a/packages/typespec-java/CONTRIBUTING.md +++ b/packages/typespec-java/CONTRIBUTING.md @@ -90,75 +90,49 @@ Make sure to run the following commands: ## Release Process -This describes how to ship a patch (hotfix) release of `@azure-tools/typespec-java` from a -`release/*` branch. - -### 1. Create the release branch and bump the version - -The overall publishing background for this repo is documented in the root -[`CONTRIBUTING.md` "Publishing" section](../../CONTRIBUTING.md#publishing) (the monthly -TypeSpec-Azure release flow). For preparing the branch and bumping this package's version -specifically, follow the [`hotfix-release` skill](../../.github/skills/hotfix-release/SKILL.md), -which walks through creating the `publish/hotfix/-` branch off the -`release/` branch and running `pnpm chronus version --ignore-policies`. - -### 2. Pin the core commit for the patch (`core-commit.json`) - -Release branches do not carry `core/` submodule updates, so bump the pin instead of the -submodule. Update the `sha` field in [`core-commit.json`](./core-commit.json) to the target -upstream `core` commit you want this patch to build and generate from. `Build-Generator.ps1` / -`Copy-Sources.ps1` (build) and `SyncTests.ps1` transiently check out that pinned commit — when it -is newer than the branch's submodule checkout — and always restore the submodule afterwards, so -the patch picks up the core changes without moving the submodule pointer. - -### 3. Sync tests from core - -Run the test sync from `packages/typespec-java/emitter-tests`: - -```powershell -pwsh ./SyncTests.ps1 -``` - -This copies the hand-written tests (`src`) and TypeSpec specs (`tsp`) from -`http-client-generator-test` in the pinned `core/` commit, syncs shared dependency/override -versions, and updates `emitter-tests/package.json` — both its own `version` and the -`file:../azure-tools-typespec-java-.tgz` dependency — to align with the new emitter -version from `package.json`. Commit any resulting changes. - -### 4. Open the PR against the release branch - -Open a PR targeting `release/` (not `main`). - -### 5. (Optional) Validate SDK regeneration from the PR emitter (before merging) - -Optionally, before merging, use the -[`typespec-java - sync sdk`](https://dev.azure.com/azure-sdk/internal/_build?definitionId=8274&_a=summary) -pipeline to regenerate the Azure SDKs from the emitter built out of this PR: - -- Leave **Emitter Version** as `none` (builds the emitter from source). -- Set **PR Id or Branch** to this PR's ID. - -This produces an SDK PR generated from the PR's emitter so you can validate the regeneration -before the emitter is released. - -### 6. Merge and auto-publish - -After the PR is merged, the emitter is automatically released by the -[`typespec-azure - Publish`](https://dev.azure.com/azure-sdk/internal/_build?definitionId=1793) -pipeline. - -### 7. Backmerge to main - -Merging into the release branch creates a backmerge branch -(`backmerge/release/-`). Open a PR from that branch targeting `main` and merge it so -the version bump and changelog are reflected in `main`. - -### 8. (Optional) Regenerate and merge the SDK PR with the released version - -Optionally, run the -[`typespec-java - sync sdk`](https://dev.azure.com/azure-sdk/internal/_build?definitionId=8274&_a=summary) -pipeline again, this time with **Emitter Version** set to the released `@azure-tools/typespec-java` -version (leaving PR Id or Branch as `none`). Review and merge the resulting SDK PR. +Shipping a `@azure-tools/typespec-java` patch is done as **two separate PRs**, both targeting the +`release/` branch. The overall publishing flow is the repo's general one — see the root +[`CONTRIBUTING.md` "Publishing" section](../../CONTRIBUTING.md#publishing) and the +[`hotfix-release` skill](../../.github/skills/hotfix-release/SKILL.md); only the +`typespec-java`-specific parts are called out here. + +### Part A — Sync core PR + +Pulls the fix in from core; **no version bump**. Example: +[#5012](https://github.com/Azure/typespec-azure/pull/5012). On a branch off `release/`: + +1. **Pin the core commit.** Release branches don't carry `core/` submodule updates, so update the + `sha` in [`core-commit.json`](./core-commit.json) to the target microsoft/typespec commit + (e.g. the HEAD of core `main`). Build and sync scripts transiently check this commit out without + moving the submodule pointer. +2. **Sync tests from core.** Run `pwsh ./SyncTests.ps1` in [`emitter-tests`](./emitter-tests): it + copies the tests/specs from the pinned core commit and aligns `emitter-tests/package.json`. +3. **Add a `fix` changelog entry** for the fix (`pnpm change add`). + +Open the PR against `release/` (not `main`) and merge it. _(Optional)_ Before merging, +validate SDK regeneration from the PR's emitter with the +[`typespec-java - sync sdk`](https://dev.azure.com/azure-sdk/internal/_build?definitionId=8274) +pipeline: leave **Emitter Version** as `none` and set **PR Id or Branch** to this PR. + +### Part B — Release PR + +Bumps the version and publishes, after Part A merges. Example: +[#4990](https://github.com/Azure/typespec-azure/pull/4990). Prepare the version bump per the +`hotfix-release` skill (creates the `publish/hotfix/-` branch off `release/` +and runs `pnpm chronus version --ignore-policies`, consuming the changeset from Part A). The `core` +submodule stays unchanged. The bump must also be reflected in `emitter-tests/package.json` (its +`version` and the `*.tgz` dependency) — rerun `pwsh ./SyncTests.ps1` or update it manually. + +Open the PR against `release/`. After it merges: + +- The emitter is auto-released by the + [`typespec-azure - Publish`](https://dev.azure.com/azure-sdk/internal/_build?definitionId=1793) + pipeline. +- Backmerge the generated branch to `main`. If the backmerge branch isn't created automatically + (e.g. the workflow failed on a name collision), create it manually from the release branch and + open the PR to `main` yourself. +- _(Optional)_ Regenerate the downstream SDKs by rerunning `typespec-java - sync sdk` with + **Emitter Version** set to the released version, and merge the resulting SDK PR. ## Trademarks