add readme

Author: msyyc

eng/tools/emitter/README.md

@@ -4,7 +4,51 @@ This directory holds files related to the TypeSpec Python emitter (`@azure-tools
 
 ## Contents
 
-- **`gen/`** — Auto-generated Python SDK test code produced by the emitter.
-  These files are regenerated automatically by the [typespec-python-regenerate](https://github.com/Azure/azure-sdk-for-python/blob/main/.github/workflows/typespec-python-regenerate.yml) workflow whenever the emitter version in `eng/emitter-package.json` is updated.
+- **`gen/`** — Auto-generated Python SDK test code (`gen/azure/` and `gen/unbranded/`) produced by the emitter.
+  These files are regenerated by the [typespec-python-regenerate](../../../.github/workflows/typespec-python-regenerate.yml) workflow.
 
 > **Do not edit files in `gen/` by hand.** They will be overwritten on the next regeneration.
+
+## Regeneration workflow
+
+The [`typespec-python-regenerate`](../../../.github/workflows/typespec-python-regenerate.yml) GitHub Actions workflow regenerates the contents of `gen/`.
+
+### Triggers
+
+- **Automatic (push)** — runs when [`eng/emitter-package.json`](../../emitter-package.json) is updated on `main`. The workflow checks out `microsoft/typespec@main` and regenerates from there.
+- **Manual (`workflow_dispatch`)** — runs from the Actions tab with one input:
+  - **`typespec_ref`** — either:
+    - `main` (default) — regenerate from `microsoft/typespec@main`, or
+    - a `microsoft/typespec` pull request URL (e.g. `https://github.com/microsoft/typespec/pull/1234`) — the workflow resolves the PR's head repo and SHA via `gh pr view` and checks out that exact commit (so unmerged PRs and fork branches work).
+
+  Any other value is rejected.
+
+### What the workflow does
+
+> **Note:** When triggering from a `microsoft/typespec` pull request URL, make sure the PR is up to date with its `main` branch first — click **Update branch** on the PR before running this workflow. Otherwise the regenerated output will be based on a stale base and may produce a confusing diff that mixes PR changes with unrelated drift from `main`.
+
+1. Checks out `azure-sdk-for-python` and the resolved `microsoft/typespec` source into `_typespec/`.
+2. Builds `_typespec/packages/http-client-python` and runs `npm run regenerate`.
+3. Copies the regenerated output into `eng/tools/emitter/gen/azure` and `eng/tools/emitter/gen/unbranded`.
+4. If anything changed, force-pushes the result to a branch:
+   - `auto/typespec-python-regenerate` when the source is `main`
+   - `auto/typespec-python-regenerate-<PR_NUMBER>` when the source is a PR URL
+5. Creates or updates a tracking issue (GitHub Actions cannot open PRs directly in this repo):
+   - **Title** uses a stable source label so retriggering from the same source reuses the existing open issue instead of creating a duplicate:
+     - `[typespec-python] Regenerate tests from microsoft/typespec@main`
+     - `[typespec-python] Regenerate tests from microsoft/typespec PR #<N>`
+   - **Body** behavior:
+     - If no open PR exists from the branch to `main`, the body contains a prefilled compare URL ("Create pull request from `<branch>`") that opens a PR with the title and body already populated.
+     - If an open PR already exists from the branch to `main`, the body links directly to that PR and notes that the existing PR has been updated with the new commit (a force-push does not close the PR).
+   - **Assignees / cc**:
+     - Manual (`workflow_dispatch`) runs are assigned to the user who triggered the run (`github.actor`).
+     - Automatic (`push`) runs are assigned to the default maintainers (`@iscai-msft`, `@msyyc`).
+
+
+### Failure notifications
+
+If the `regenerate` job fails, a separate `notify-on-failure` job opens a new issue titled `[typespec-python] Regeneration workflow failed`, labeled `typespec-python`, and always assigned to `@iscai-msft` and `@msyyc` regardless of trigger.
+
+### Concurrency
+
+The workflow uses `concurrency: { group: <workflow>, cancel-in-progress: true }`, so a newer run cancels any in-flight run.