Skip to content

[Automated][tcgc] Update TCGC documentation for recent behavioral changes#4398

Merged
tadelesh merged 7 commits into
mainfrom
docs/tcgc-incremental-update-2026-05-04-0ffcd4418218bbd6
May 11, 2026
Merged

[Automated][tcgc] Update TCGC documentation for recent behavioral changes#4398
tadelesh merged 7 commits into
mainfrom
docs/tcgc-incremental-update-2026-05-04-0ffcd4418218bbd6

Conversation

@lirenhe
Copy link
Copy Markdown
Member

@lirenhe lirenhe commented May 8, 2026 •
edited by tadelesh
Loading

Update TCGC documentation for recent behavioral changes

cc @tadelesh

Resolve: #4367

Also resolve: #4352

github-actions Bot and others added 2 commits May 4, 2026 11:00
@github-actions
docs: update hierarchyBuilding docs for new property reconciliation b…
d92b427 
…ehavior

Reflect the major overhaul of the @hierarchyBuilding decorator:
- Remove ClientTabs (legacy decorator, TypeSpec-only examples)
- Document new property reconciliation rules: lifting, dropping,
  type compatibility checks, and discriminator preservation
- Add brownfield ARM resource rebasing use case
- Update title to 'Legacy Hierarchy Building'

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@github-actions
docs(tcgc): update documentation for recent behavioral changes
75afdfb 
Update documentation for:
- @responseAsBool: clarify boolean is client-side concept, HTTP responses have no body type
- @apiversion(false): document keeping parameter on operation level
- @hierarchyBuilding: document property lifting and reconciliation behavior
- Usage propagation: document readonly property Input flag stripping
- Content-Type/Accept: document multi-content-type accept header as constant
- inconsistent-multiple-service-dependency: document new diagnostic
- Body apiVersion property: document name-matching only applies to HTTP metadata

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@lirenhe lirenhe mentioned this pull request May 8, 2026
Closed
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 8, 2026 •
edited
Loading

⚡ Benchmark Results

⚠️ 28 metric(s) regressed above the +5% threshold:

Metric Baseline Current Change
 ↳ linter/@azure-tools/typespec-azure-core/bad-record-type 🟢 0.2ms 🟢 0.2ms +8.4% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/friendly-name 🟢 0.6ms 🟢 0.7ms +8.5% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/key-visibility-required 🟢 0.2ms 🟢 0.2ms +8.1% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-closed-literal-union 🟢 0.3ms 🟢 0.3ms +5.2% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-explicit-routes-resource-ops 🟢 0.1ms 🟢 0.1ms +10.0% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-format 🟢 0.5ms 🟢 0.5ms +9.8% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-generic-numeric 🟢 0.4ms 🟢 0.6ms +47.0% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-legacy-usage 🟢 1.1ms 🟢 1.2ms +6.0% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-query-explode 🔴 21.0ms 🔴 22.5ms +7.2% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-rest-library-interfaces 🟢 0.0ms 🟢 0.0ms +8.4% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-unknown 🟢 0.2ms 🟢 0.2ms +12.5% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/operation-missing-api-version 🟢 0.2ms 🟢 0.2ms +16.9% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/require-versioned 🟢 0.0ms 🟢 0.0ms +20.9% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/spread-discriminated-model 🟢 0.2ms 🟢 0.3ms +12.2% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/use-standard-operations 🟢 0.1ms 🟢 0.1ms +14.3% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-no-record 🟢 0.4ms 🟢 0.4ms +25.9% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-action-no-segment 🟢 0.2ms 🟢 0.3ms +10.0% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-interface-requires-decorator 🟢 0.0ms 🟢 0.0ms +7.0% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-action-verb 🟢 0.1ms 🟢 0.1ms +17.1% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-envelope-property 🟢 0.1ms 🟢 0.1ms +7.8% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-operation 🟢 0.2ms 🟢 0.2ms +20.6% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-operation-response 🟢 5.4ms 🟢 7.7ms +42.6% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-provisioning-state 🟢 0.1ms 🟢 0.1ms +12.4% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/improper-subscription-list-operation 🟢 0.0ms 🟢 0.0ms +31.1% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/missing-x-ms-identifiers 🟢 0.3ms 🟢 0.3ms +18.8% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/no-response-body 🔴 24.9ms 🔴 28.3ms +13.6% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/patch-envelope 🟢 0.1ms 🟢 0.2ms +10.0% 🔴
 ↳ linter/@azure-tools/typespec-client-generator-core/require-client-suffix 🟢 0.2ms 🟢 0.2ms +7.0% 🔴
Full details – comparing 092e778 vs baseline 8a0b6e3
Metric Baseline Current Change
total 🔴 840.9ms 🔴 753.6ms -10.4% 🟢
loader 🟢 164.2ms 🟢 135.0ms -17.8% 🟢
resolver 🟢 17.7ms 🟢 17.6ms -0.5%
checker 🟡 204.7ms 🟢 180.6ms -11.8% 🟢
validation 🟢 43.3ms 🟢 41.5ms -4.2%
 ↳ validation/@azure-tools/typespec-azure-core 🟢 6.9ms 🟢 6.0ms -12.8% 🟢
 ↳ validation/@typespec/http 🟢 6.7ms 🟢 6.1ms -9.6% 🟢
 ↳ validation/@typespec/rest 🟢 0.6ms 🟢 0.6ms -5.2% 🟢
 ↳ validation/@typespec/versioning 🔴 27.4ms 🔴 27.3ms -0.2%
 ↳ validation/compiler 🟢 1.7ms 🟢 1.5ms -11.1% 🟢
linter 🟢 142.8ms 🟢 138.3ms -3.1%
 ↳ linter/@azure-tools/typespec-azure-core/auth-required 🟢 0.0ms 🟢 0.0ms -0.3%
 ↳ linter/@azure-tools/typespec-azure-core/bad-record-type 🟢 0.2ms 🟢 0.2ms +8.4% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/byos 🟢 5.9ms 🟢 6.1ms +2.3%
 ↳ linter/@azure-tools/typespec-azure-core/casing-style 🟢 0.6ms 🟢 0.5ms -12.9% 🟢
 ↳ linter/@azure-tools/typespec-azure-core/composition-over-inheritance 🟢 0.1ms 🟢 0.1ms +3.2%
 ↳ linter/@azure-tools/typespec-azure-core/documentation-required 🟢 0.8ms 🟢 0.8ms -5.6% 🟢
 ↳ linter/@azure-tools/typespec-azure-core/friendly-name 🟢 0.6ms 🟢 0.7ms +8.5% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/key-visibility-required 🟢 0.2ms 🟢 0.2ms +8.1% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/known-encoding 🟢 0.2ms 🟢 0.3ms +1.5%
 ↳ linter/@azure-tools/typespec-azure-core/long-running-polling-operation-required 🟢 0.3ms 🟢 0.3ms -6.0% 🟢
 ↳ linter/@azure-tools/typespec-azure-core/no-case-mismatch 🟢 0.2ms 🟢 0.2ms -0.9%
 ↳ linter/@azure-tools/typespec-azure-core/no-closed-literal-union 🟢 0.3ms 🟢 0.3ms +5.2% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-enum 🟢 0.0ms 🟢 0.0ms -4.5%
 ↳ linter/@azure-tools/typespec-azure-core/no-error-status-codes 🟢 0.1ms 🟢 0.1ms -0.8%
 ↳ linter/@azure-tools/typespec-azure-core/no-explicit-routes-resource-ops 🟢 0.1ms 🟢 0.1ms +10.0% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-format 🟢 0.5ms 🟢 0.5ms +9.8% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-generic-numeric 🟢 0.4ms 🟢 0.6ms +47.0% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-header-explode 🔴 20.3ms 🟡 19.2ms -5.3% 🟢
 ↳ linter/@azure-tools/typespec-azure-core/no-legacy-usage 🟢 1.1ms 🟢 1.2ms +6.0% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-multiple-discriminator 🟢 0.1ms 🟢 0.1ms -8.8% 🟢
 ↳ linter/@azure-tools/typespec-azure-core/no-nullable 🟢 0.2ms 🟢 0.2ms -7.4% 🟢
 ↳ linter/@azure-tools/typespec-azure-core/no-offsetdatetime 🟢 1.2ms 🟢 1.2ms -4.3%
 ↳ linter/@azure-tools/typespec-azure-core/no-openapi 🟢 2.1ms 🟢 2.0ms -6.2% 🟢
 ↳ linter/@azure-tools/typespec-azure-core/no-private-usage 🟢 1.8ms 🟢 1.8ms -0.6%
 ↳ linter/@azure-tools/typespec-azure-core/no-query-explode 🔴 21.0ms 🔴 22.5ms +7.2% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-response-body 🔴 24.7ms 🔴 21.6ms -12.8% 🟢
 ↳ linter/@azure-tools/typespec-azure-core/no-rest-library-interfaces 🟢 0.0ms 🟢 0.0ms +8.4% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-route-parameter-name-mismatch 🟢 5.8ms 🟢 5.2ms -10.5% 🟢
 ↳ linter/@azure-tools/typespec-azure-core/no-rpc-path-params 🟢 0.2ms 🟢 0.2ms -12.7% 🟢
 ↳ linter/@azure-tools/typespec-azure-core/no-string-discriminator 🟢 0.1ms 🟢 0.0ms -13.1% 🟢
 ↳ linter/@azure-tools/typespec-azure-core/no-unknown 🟢 0.2ms 🟢 0.2ms +12.5% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/no-unnamed-union 🟢 0.3ms 🟢 0.3ms +4.4%
 ↳ linter/@azure-tools/typespec-azure-core/operation-missing-api-version 🟢 0.2ms 🟢 0.2ms +16.9% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/request-body-problem 🟢 0.3ms 🟢 0.2ms -16.8% 🟢
 ↳ linter/@azure-tools/typespec-azure-core/require-versioned 🟢 0.0ms 🟢 0.0ms +20.9% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/response-schema-problem 🔴 23.3ms 🔴 21.7ms -6.8% 🟢
 ↳ linter/@azure-tools/typespec-azure-core/rpc-operation-request-body 🟢 0.3ms 🟢 0.3ms -5.0% 🟢
 ↳ linter/@azure-tools/typespec-azure-core/spread-discriminated-model 🟢 0.2ms 🟢 0.3ms +12.2% 🔴
 ↳ linter/@azure-tools/typespec-azure-core/use-standard-names 🟢 5.4ms 🟢 4.8ms -11.9% 🟢
 ↳ linter/@azure-tools/typespec-azure-core/use-standard-operations 🟢 0.1ms 🟢 0.1ms +14.3% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-common-types-version 🟢 6.3ms 🟢 6.1ms -3.7%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-custom-resource-no-key 🟢 0.1ms 🟢 0.1ms -16.2% 🟢
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-custom-resource-usage-discourage 🟢 0.1ms 🟢 0.1ms +3.0%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-delete-operation-response-codes 🟢 8.8ms 🟢 6.5ms -25.4% 🟢
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-no-record 🟢 0.4ms 🟢 0.4ms +25.9% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-post-operation-response-codes 🟢 0.8ms 🟢 0.6ms -20.7% 🟢
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-put-operation-response-codes 🟢 0.0ms 🟢 0.0ms +2.3%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-action-no-segment 🟢 0.2ms 🟢 0.3ms +10.0% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-duplicate-property 🟢 0.1ms 🟢 0.1ms -8.2% 🟢
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-interface-requires-decorator 🟢 0.0ms 🟢 0.0ms +7.0% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-action-verb 🟢 0.1ms 🟢 0.1ms +17.1% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-envelope-property 🟢 0.1ms 🟢 0.1ms +7.8% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-version-format 🟢 0.1ms 🟢 0.1ms -8.2% 🟢
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-key-invalid-chars 🟢 0.3ms 🟢 0.3ms -1.1%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-name-pattern 🟢 0.0ms 🟢 0.0ms -23.8% 🟢
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-operation 🟢 0.2ms 🟢 0.2ms +20.6% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-operation-response 🟢 5.4ms 🟢 7.7ms +42.6% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-patch 🟢 0.4ms 🟢 0.4ms +2.6%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-path-segment-invalid-chars 🟢 0.2ms 🟢 0.2ms -0.7%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/arm-resource-provisioning-state 🟢 0.1ms 🟢 0.1ms +12.4% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/beyond-nesting-levels 🟢 0.1ms 🟢 0.1ms -0.1%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/empty-updateable-properties 🟢 0.2ms 🟢 0.2ms -1.7%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/improper-subscription-list-operation 🟢 0.0ms 🟢 0.0ms +31.1% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/lro-location-header 🟡 17.5ms 🟡 17.8ms +1.8%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/missing-operations-endpoint 🟢 0.0ms 🟢 0.0ms -5.5% 🟢
 ↳ linter/@azure-tools/typespec-azure-resource-manager/missing-x-ms-identifiers 🟢 0.3ms 🟢 0.3ms +18.8% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/no-empty-model 🟢 0.1ms 🟢 0.1ms +0.7%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/no-resource-delete-operation 🟢 0.2ms 🟢 0.2ms -12.0% 🟢
 ↳ linter/@azure-tools/typespec-azure-resource-manager/no-response-body 🔴 24.9ms 🔴 28.3ms +13.6% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/patch-envelope 🟢 0.1ms 🟢 0.2ms +10.0% 🔴
 ↳ linter/@azure-tools/typespec-azure-resource-manager/resource-name 🟢 0.2ms 🟢 0.2ms -0.6%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/secret-prop 🟢 2.7ms 🟢 2.7ms -2.9%
 ↳ linter/@azure-tools/typespec-azure-resource-manager/unsupported-type 🟢 0.4ms 🟢 0.4ms -6.4% 🟢
 ↳ linter/@azure-tools/typespec-azure-resource-manager/version-progression 🟢 0.0ms 🟢 0.0ms -1.2%
 ↳ linter/@azure-tools/typespec-client-generator-core/property-name-conflict 🟢 1.1ms 🟢 1.1ms -4.5%
 ↳ linter/@azure-tools/typespec-client-generator-core/require-client-suffix 🟢 0.2ms 🟢 0.2ms +7.0% 🔴
emit 🟡 268.3ms 🟡 240.6ms -10.3% 🟢
 ↳ emit/@azure-tools/typespec-autorest 🟢 159.0ms 🟢 150.9ms -5.1% 🟢
 ↳ emit/@typespec/openapi3 🟢 163.8ms 🟢 134.5ms -17.9% 🟢
 ↳ emit/@typespec/openapi3/compute 🟢 150.0ms 🟢 121.0ms -19.3% 🟢
 ↳ emit/@typespec/openapi3/write 🟢 13.7ms 🟢 13.4ms -2.3%

Averaged across 3 specs (azure-arm-resource-manager, azure-core-dataplane, azure-full).
Threshold: changes > ±5% are highlighted.
🟢 Fast · 🟡 Moderate (stages >200ms, rules >10ms) · 🔴 Slow (stages >400ms, rules >20ms)

@azure-sdk
Copy link
Copy Markdown
Collaborator

azure-sdk commented May 8, 2026

No changes needing a change description found.

@azure-sdk
Copy link
Copy Markdown
Collaborator

azure-sdk commented May 8, 2026

You can try these changes here

🛝 Playground 🌐 Website

tadelesh
tadelesh reviewed May 11, 2026
View reviewed changes
Copy link
Copy Markdown
Member

@tadelesh tadelesh left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot Resolve comments.

Comment thread website/src/content/docs/docs/howtos/Generate client libraries/10versioning.mdx Outdated
Comment thread website/src/content/docs/docs/howtos/Generate client libraries/10versioning.mdx
Comment thread website/src/content/docs/docs/howtos/Generate client libraries/11hierarchyBuilding.mdx
Copy link
Copy Markdown
Contributor

Copilot AI commented May 11, 2026

@copilot Resolve comments.

Resolved in 4a857c5. I addressed the open review comments and pushed the documentation updates.

Copilot AI requested a review from tadelesh May 11, 2026 03:03
@tadelesh
Copy link
Copy Markdown
Member

tadelesh commented May 11, 2026

@copilot For all language codes, you need to use [doc-example-generator](https://github.com/Azure/typespec-azure/tree/main/.github/skills/doc-example-generator) skill to generate the code.

Copy link
Copy Markdown
Contributor

Copilot AI commented May 11, 2026

@copilot For all language codes, you need to use [doc-example-generator](https://github.com/Azure/typespec-azure/tree/main/.github/skills/doc-example-generator) skill to generate the...

Done in 7bebf6e. I used the doc-example-generator skill to compile each TypeSpec example and replaced every language tab in both 10versioning.mdx (@apiVersion(false) example) and 11hierarchyBuilding.mdx (all six examples) with the actual Python, C#, TypeScript, Java, and Go API surface extracted from the real emitter output.

tadelesh
tadelesh approved these changes May 11, 2026 •
edited
Loading
View reviewed changes
@tadelesh tadelesh enabled auto-merge May 11, 2026 05:08
@tadelesh tadelesh added this pull request to the merge queue May 11, 2026
Merged via the queue into main with commit 5849136 May 11, 2026
23 of 27 checks passed
@tadelesh tadelesh deleted the docs/tcgc-incremental-update-2026-05-04-0ffcd4418218bbd6 branch May 11, 2026 05:46
github-actions Bot added a commit that referenced this pull request May 11, 2026
@github-actions
docs(tcgc): document server URL template param API version detection
243c11f 
Update versioning docs to explain that name-based API version detection
applies to both HTTP metadata parameters and server URL template
parameters declared in @server. This documents the fix from PR #4341
regression where server URL template params named apiVersion/api-version
were not recognized.

Also update knowledge base with lessons from PR #4398 feedback.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@github-actions github-actions Bot mentioned this pull request May 11, 2026
Open
@timotheeguerin timotheeguerin mentioned this pull request May 11, 2026
Merged
@github-actions github-actions Bot mentioned this pull request May 12, 2026
Draft
@tadelesh tadelesh mentioned this pull request May 13, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@tadelesh tadelesh tadelesh approved these changes

@bterlson bterlson Awaiting requested review from bterlson bterlson is a code owner

@markcowl markcowl Awaiting requested review from markcowl markcowl is a code owner

@timotheeguerin timotheeguerin Awaiting requested review from timotheeguerin timotheeguerin is a code owner

Assignees

No one assigned

Labels

eng meta:website TypeSpec.io updates

Projects

None yet

Milestone

No milestone

4 participants

@lirenhe @azure-sdk @tadelesh