Azure / Azure/typespec-azure

[Automated][tcgc][skip chg] Update TCGC override response documentation

Closed
#5,473 0 comments 0 reactions 0 assignees View on GitHub
agentic-workflows docs lib:tcgc
Dominant language
TypeScript
Stars
27
Forks
90
Avg merge
1d 22h
Merged PRs (30d)
156

Description

## Summary

- clarify that plain `@override` return types are ignored and do not trigger response compatibility diagnostics
- document that `replaceResponseWithVoid` and `replaceResponseWithBytes` are the supported response replacement mechanisms
- regenerate decorator reference docs and update the documentation updater knowledge and metadata

## Validation

- TCGC dependency build
- 28 targeted tests
- reference documentation regeneration
- `pnpm format`
- `pnpm lint`
- cspell and `git diff --check`

> Generated by [Documentation Update Agent](https://github.com/Azure/typespec-azure/actions/runs/34826696485) · gpt56 · 289.7 AIC · ⌖ 32.9 AIC · ⊞ 19.1K · [◷](https://github.com/search?q=repo%3AAzure%2Ftypespec-azure+%22gh-aw-workflow-id%3A+doc-update%22&type=pullrequests)

---

> [!NOTE]
> This was originally intended as a pull request, but GitHub Actions is not permitted to create or approve pull requests in this repository.
> The changes have been pushed to branch `docs/tcgc-incremental-20260914-3e1a8a4f4a55a898`.
>
> **[Click here to create the pull request](https://github.com/Azure/typespec-azure/compare/main...docs/tcgc-incremental-20260914-3e1a8a4f4a55a898?expand=1&title=%5BAutomated%5D%5Btcgc%5D%5Bskip%20chg%5D%20Update%20TCGC%20override%20response%20documentation)**

To fix the permissions issue, go to **Settings** → **Actions** → **General** and enable **Allow GitHub Actions to create and approve pull requests**. See also: [gh-aw FAQ](https://github.github.com/gh-aw/reference/faq/#why-is-my-create-pull-request-workflow-failing-with-github-actions-is-not-permitted-to-create-or-approve-pull-requests)

Show patch preview (132 of 132 lines)

```diff
From 7a739d678a31f5af4611fbb9b46b79b1be9b5eea Mon Sep 17 00:00:00 2001
X-GH-AW-Base-Commit: 5f4088cb98034d388da0ca32db6c2172103c3abe
From: "github-actions[bot]"
Date: Mon, 14 Sep 2026 10:16:29 +0000
Subject: [PATCH] Update TCGC override response documentation

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
eng/scripts/doc-updater/knowledge/tcgc.md | 3 ++-
eng/scripts/doc-updater/knowledge/tcgc.meta.json | 4 ++--
packages/typespec-client-generator-core/lib/decorators.tsp | 6 ++++--
.../docs/docs/howtos/Generate client libraries/04method.mdx | 6 +++---
.../libraries/typespec-client-generator-core/guideline.md | 2 +-
.../typespec-client-generator-core/reference/decorators.md | 6 ++++--
6 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/eng/scripts/doc-updater/knowledge/tcgc.md b/eng/scripts/doc-updater/knowledge/tcgc.md
index de685f2f1..22cf5e2ea 100644
--- a/eng/scripts/doc-updater/knowledge/tcgc.md
+++ b/eng/scripts/doc-updater/knowledge/tcgc.md
@@ -19,7 +19,7 @@
5. `@operationGroup(target, scope?)` — DEPRECATED, use @client
6. `@usage(target, value, scope?)` — mark model/enum/union/namespace usage (input/output/json/xml); on namespace, propagates recursively to all contained types
7. `@access(target, value, scope?)` — public/internal visibility
-8. `@override(target, override, scope?)` — customize method signatures
+8. `@override(target, override, scope?)` — customize method parameters; a plain override's declared return type is ignored, while response replacement requires `replaceResponseWithVoid` or `replaceResponseWithBytes`
9. `@useSystemTextJsonConverter(target, scope?)` — C# backward compat only
10. `@clientInitialization(target, options, scope?)` — customize client init; options has parameters model and initializedBy flags
11. `@paramAlias(target, alias, scope?)` — alias client init parameter names
@@ -118,6 +118,7 @@ namespace
... (truncated)
```

Contributor guide

Open the contributing guide

Research direction

Start with packages/typespec-client-generator-core/lib/decorators.tsp and the related reference, guideline, how-to, and doc-updater knowledge files listed in the patch preview. Run the 28 targeted tests, reference documentation regeneration, pnpm format, pnpm lint, cspell, and git diff --check; done means the TCGC override response behavior is consistently documented across those files.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation, tooling
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.