docs: clarify Http.File request body compatibility

Add a compact design note explaining why TypeSpec Http.File emitting IO[bytes] | bytes is backward compatible with legacy Swagger file APIs that accepted bytes.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: msyyc

docs/developer/http_file_body_compatibility.md

@@ -0,0 +1,40 @@
+# `Http.File` request body compatibility for Python
+
+## Problem
+
+When a TypeSpec operation uses `Http.File` as the request body type, the Python emitter generates an SDK method input type of `IO[bytes] | bytes`.
+
+For migrated Swagger APIs, this must remain compatible with previous SDKs where Swagger `type: file` was represented as `bytes`.
+
+## Compact example
+
+TypeSpec:
+
+```typespec
+import "@typespec/http";
+
+using TypeSpec.Http;
+
+@route("/files")
+namespace Files;
+
+@post
+op upload(@body body: Http.File): void;
+```
+
+Python SDK (generated shape):
+
+```python
+from typing import IO, Union
+
+def upload(self, body: Union[IO[bytes], bytes], **kwargs) -> None:
+    ...
+```
+
+## Compatibility statement
+
+- Swagger `type: file` callers pass `bytes`.
+- `bytes` is still accepted by `Union[IO[bytes], bytes]`.
+- Existing `bytes`-based callsites continue to work without code changes.
+
+Therefore, migrating this shape from Swagger to TypeSpec is **non-breaking** for existing Python SDK consumers.

docs/developer/readme.md

@@ -12,3 +12,7 @@ To test an unpublished branded emitter tarball, please follow these steps:
 6. Paste the url as the version for the `"@azure-tools/typespec-python"` package
 7. Run `tsp-client generate-lock-file` from the `azure-sdk-for-python/eng` folder
 8. Go to the sdk you'd like to regenerate with the tarball, then run `tsp-client update` how you normally would
+
+## Design Notes
+
+- [`Http.File` request body compatibility for Python](./http_file_body_compatibility.md)