Add 0.68 tcgc newsletter (#4439)

Co-authored-by: tadelesh <chenjieshi@microsoft.com>

Author: tadelesh

packages/typespec-client-generator-core/newsletter/0.68.md

@@ -0,0 +1,238 @@
+# TCGC Monthly Newsletter — `@azure-tools/typespec-client-generator-core` 0.68
+
+Hey everyone! This newsletter covers the latest TCGC releases (0.67.2 through 0.68.0) with the new `exact()` function for precise client naming, `serializationOptions` for body/response types, enhanced hierarchy building, and important bug fixes. As always, I welcome any and all feedback!
+
+## ⭐ What's New in This Release
+
+- `exact()` Function for `@clientName` ⭐ (Major Feature) — [docs](https://azure.github.io/typespec-azure/docs/howtos/generate-client-libraries/09renaming/#preserving-exact-casing)
+- `serializationOptions` on Body Parameters and Responses ⭐ (Major Feature) — [docs](https://azure.github.io/typespec-azure/docs/howtos/generate-client-libraries/08types/)
+- Enhanced `@Legacy.hierarchyBuilding` — Arbitrary Inheritance Replacement — [docs](https://azure.github.io/typespec-azure/docs/howtos/generate-client-libraries/11hierarchybuilding/)
+- `inconsistent-multiple-service-dependency` Warning — [docs](https://azure.github.io/typespec-azure/docs/howtos/generate-client-libraries/03client/#one-client-from-multiple-services)
+- Bug Fixes & Improvements
+
+---
+
+## ⚠️ Emitter Behavior Changes
+
+Emitter authors, heads up! This release includes a **breaking change** that requires attention. See the detailed section below for migration guidance.
+
+- **Multi-content-type `accept` parameter is now a string constant** — When an operation's response declares multiple content types (e.g., `Http.File<"image/png" | "image/jpeg">`), the synthetic `accept` parameter is now a single string constant (comma-joined, structured types listed first) instead of an enum. This avoids incorrectly modeling such operations as content negotiation. Use `@sharedRoute` to split an operation if real content negotiation is required.
+- **External alternate types no longer leak into `sdkPackage`** — Types that are only used within external alternate types are no longer included in `sdkPackage.models`, `sdkPackage.enums`, or `sdkPackage.unions`. If your emitter previously relied on these types being present in the package-level collections, they will now be absent.
+
+---
+
+## ⭐ `exact()` Function for `@clientName` (0.68.0)
+
+📖 **Docs**: [Preserving Exact Casing](https://azure.github.io/typespec-azure/docs/howtos/generate-client-libraries/09renaming/#preserving-exact-casing) · [`@clientName` reference](https://azure.github.io/typespec-azure/docs/libraries/typespec-client-generator-core/reference/decorators/#@Azure.ClientGenerator.Core.clientName)
+
+A new `exact()` function that preserves client names **without language-specific casing transformations**. Previously, names provided via `@clientName` would still be subject to emitter-specific casing rules (e.g., `PascalCase` for C#, `snake_case` for Python). Now you can opt out of those transformations entirely.
+
+### How It Works
+
+Wrap the name string in `exact()` when calling `@@clientName`:
+
+```typespec
+// Without exact — emitter may transform casing
+@@clientName(MyService.TestModel, "RenamedModel");
+
+// With exact — name is preserved as-is, no casing transformation
+#suppress "experimental-feature" "using exact"
+@@clientName(MyService.TestModel, exact("hello_world"));
+```
+
+Works with language scoping too:
+
+```typespec
+// Only Python uses the exact name; other languages use the original
+#suppress "experimental-feature" "using exact"
+@@clientName(MyService.TestModel, exact("hello_world"), "python");
+```
+
+Applies to models, properties, enums, and operations:
+
+```typespec
+#suppress "experimental-feature" "using exact"
+@@clientName(MyService.TestModel.myProp, exact("my_exact_prop"));
+
+#suppress "experimental-feature" "using exact"
+@@clientName(MyService.Status, exact("my_status_enum"));
+
+#suppress "experimental-feature" "using exact"
+@@clientName(MyService.testOp, exact("my_exact_op"));
+```
+
+What Emitter Authors Gain: A new `isExactName` boolean field on `SdkModelType`, `SdkEnumType`, `SdkUnionType`, and `SdkModelPropertyTypeBase`. When `isExactName` is `true`, emitters should skip their language-specific casing transformations and use the name verbatim.
+
+---
+
+## ⭐ `serializationOptions` on Body Parameters and Responses (0.68.0)
+
+📖 **Docs**: [Generated Types](https://azure.github.io/typespec-azure/docs/howtos/generate-client-libraries/08types/)
+
+A new `serializationOptions` property on `SdkBodyParameter` and `SdkHttpResponse`/`SdkHttpErrorResponse` that tells emitters **how to serialize/deserialize the request or response body**. This is especially important for **basic (non-model) body types** — scalars like `string`, `bytes`, or `int32` — where previously emitters had no way to know the serialization format from the type alone.
+
+### The Problem
+
+When the body type is a model, emitters could already inspect the model's own `serializationOptions` to determine JSON/XML wire names. But when the body is a basic type (e.g., `@body body: string` or `@body body: bytes`), there's no model to inspect — emitters had to parse content-type strings themselves to figure out how to serialize.
+
+### The Solution
+
+`serializationOptions` is now available directly on `SdkBodyParameter` and `SdkHttpResponseBase`, providing format info regardless of body type:
+
+```typescript
+// Emitter code — determine how to serialize a basic-type body
+const bodyParam = httpOperation.bodyParam;
+
+if (bodyParam.serializationOptions.json) {
+  // Body should be serialized as JSON (e.g., a raw string sent as JSON)
+} else if (bodyParam.serializationOptions.xml) {
+  // Body should be serialized as XML
+} else if (bodyParam.serializationOptions.binary) {
+  // Body is binary (file upload, octet-stream, etc.)
+  const { isFile, isText, contentTypes } = bodyParam.serializationOptions.binary;
+}
+```
+
+```typespec
+// Basic type body — emitters previously couldn't determine format
+op uploadRawData(@header contentType: "application/octet-stream", @body data: bytes): void;
+// → bodyParam.serializationOptions.binary is populated
+
+op sendMessage(@header contentType: "application/json", @body message: string): void;
+// → bodyParam.serializationOptions.json is populated
+```
+
+For model bodies, `serializationOptions` remains available on the model type itself and its properties (providing wire names per format), and is now **also** mirrored on the body parameter for consistency:
+
+```typespec
+model Blob {
+  @encodedName("application/json", "newId")
+  id: string;
+}
+
+op test(@body body: Blob): void;
+// → bodyParam.serializationOptions.json is populated
+// → model.properties[0].serializationOptions.json.name === "newId"
+```
+
+What Emitter Authors Gain: A single, consistent way to determine serialization format for **all** body types — models, scalars, and files alike. No more parsing content-type strings manually for basic-type bodies.
+
+---
+
+## 🏗️ Enhanced `@Legacy.hierarchyBuilding` — Arbitrary Inheritance Replacement (0.68.0)
+
+📖 **Docs**: [Legacy Hierarchy Building](https://azure.github.io/typespec-azure/docs/howtos/generate-client-libraries/11hierarchybuilding/)
+
+The `@Legacy.hierarchyBuilding` decorator no longer requires the target to be a property-superset of the new base model. Properties contributed by removed intermediate parents are now **automatically lifted** onto the target, preserving the observable property set.
+
+### Before (0.67.x)
+
+`@Legacy.hierarchyBuilding` could only rebase to a sibling that already had all the parent's properties. Attempting to rebase to an unrelated model would fail.
+
+### After (0.68.0)
+
+Rebase works to arbitrary ancestor models. Missing properties from removed intermediates are lifted:
+
+```typespec
+@discriminator("kind")
+model A {
+  kind: string;
+}
+
+alias BContent = {
+  foo: string;
+};
+
+model B extends A {
+  kind: "B";
+  ...BContent;
+}
+
+// C now inherits from B instead of A — foo is NOT required on C
+// because BContent is already on B
+@Legacy.hierarchyBuilding(B)
+model C extends A {
+  kind: "C";
+  ...BContent;
+  bar: string;
+}
+```
+
+Result: `C.baseModel` becomes `B`, and `C.properties` contains only `kind` and `bar` (since `foo` is inherited from `B`).
+
+What Emitter Authors Gain: More flexibility for ARM Compute-style migrations where models need to be rebased to different points in the hierarchy without redeclaring all intermediate properties.
+
+---
+
+## 🔔 `inconsistent-multiple-service-dependency` Warning (0.68.0)
+
+📖 **Docs**: [Multi-Service Clients](https://azure.github.io/typespec-azure/docs/howtos/generate-client-libraries/03client/#one-client-from-multiple-services)
+
+A new warning diagnostic that fires when services merged into a single client (via `autoMergeService`) declare **diverging `@useDependency` versions** for the same shared library (e.g., ARM common-types v5 vs. v6).
+
+What Spec Authors Should Do: Align shared dependency versions across all services merged into one client to avoid generating duplicated or diverged models in the SDK.
+
+---
+
+## 🐛 Bug Fixes & Improvements
+
+Related docs: [`@clientLocation`](https://azure.github.io/typespec-azure/docs/howtos/generate-client-libraries/04method/#using-clientlocation-to-control-parameter-placement) · [`@apiVersion`](https://azure.github.io/typespec-azure/docs/libraries/typespec-client-generator-core/reference/decorators/#@Azure.ClientGenerator.Core.apiVersion)
+
+**`@clientLocation` with `@override` — Wrong `methodParameterSegments` (0.67.3 + 0.68.0)**
+
+- Issue: Operations using both `@clientLocation` and `@override` produced incorrect `methodParameterSegments`.
+- Fix: [#4302](https://github.com/Azure/typespec-azure/pull/4302), [#4344](https://github.com/Azure/typespec-azure/pull/4344)
+
+**`@apiVersion(false)` Ignored by `isOnClient()` (0.67.2)**
+
+- Issue: `@apiVersion(false)` was ignored when other operations had already elevated an api-version parameter to client level.
+- Fix: [#4234](https://github.com/Azure/typespec-azure/pull/4234)
+
+**Duplicate Client Entries in Multi-Service (0.67.2)**
+
+- Issue: Calling `createSdkContext` multiple times or merging sub clients with the same name in multi-service cases produced duplicate client entries.
+- Fix: [#4253](https://github.com/Azure/typespec-azure/pull/4253)
+
+**Readonly Property Usage Propagation (0.67.2)**
+
+- Issue: Readonly properties didn't properly strip the `Input` flag from combined usage values, and `ignoreSubTypeStack` was unbalanced.
+- Fix: [#4235](https://github.com/Azure/typespec-azure/pull/4235)
+
+**Error Response in Intersection Types (0.67.1)**
+
+- Issue: Error responses in intersection types (e.g., `ArmAcceptedResponse & ErrorResponse`) weren't classified as exceptions, causing false `unexpected-pageable-operation-return-type` diagnostics.
+- Fix: [#4215](https://github.com/Azure/typespec-azure/pull/4215)
+
+**`bytes` Encoding in `HttpPart` for Multipart (0.67.4)**
+
+- Issue: `bytes` in `HttpPart` for `multipart/form-data` was incorrectly encoded as `base64` instead of `bytes`.
+- Fix: [#4345](https://github.com/Azure/typespec-azure/pull/4345)
+
+**Wrong API Version Param Judgement (0.68.0)**
+
+- Issue: A body model property named `apiVersion`/`api-version` was incorrectly flagged as `isApiVersionParam` with a service-derived `clientDefaultValue`. Only operation parameters should be considered API version parameters.
+- Fix: [#4341](https://github.com/Azure/typespec-azure/pull/4341), [#4386](https://github.com/Azure/typespec-azure/pull/4386)
+
+**`@responseAsBool` on HEAD Operations (0.68.0)**
+
+- Issue: `@responseAsBool` incorrectly set `bodyType` on HEAD operation HTTP responses.
+- Fix: [#4343](https://github.com/Azure/typespec-azure/pull/4343)
+
+**External Alternate Types Leaking into Package (0.68.0)**
+
+- Issue: Types only used within external alternate types were incorrectly included in `sdkPackage` models, enums, or unions.
+- Fix: [#4236](https://github.com/Azure/typespec-azure/pull/4236)
+
+---
+
+## 🎉 The Bottom Line
+
+The headline feature is **`exact()`** — a simple but powerful addition that lets spec authors preserve client names exactly as written, bypassing emitter casing transformations. This is especially useful for names with deliberate casing (acronyms, legacy names, cross-language consistency).
+
+**`serializationOptions`** on body parameters and responses gives emitters a clear, format-aware contract for serialization — no more inferring JSON vs. XML from content-type strings.
+
+The **breaking change** to multi-content-type `accept` parameters (string constant instead of enum) properly distinguishes "accept all these types" from true content negotiation. If you have emitter logic that pattern-matches on enum-typed accept parameters, update it to handle string constants.
+
+Special thanks to all emitter authors for your continued collaboration and feedback! 🙌
+
+Thanks, @Chenjie and @Isabella