From ac6ec4ec85a144dabea28ad5bfba255efc184c47 Mon Sep 17 00:00:00 2001
From: Steve Ayers <sayers@buf.build>
Date: Fri, 8 Nov 2024 17:54:44 -0500
Subject: [PATCH] Migration guide for v2

---
 README.md | 128 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 128 insertions(+)

diff --git a/README.md b/README.md
index 30c261011..4d5b95cff 100644
--- a/README.md
+++ b/README.md
@@ -68,6 +68,134 @@ You can serve your Connect RPCs with vanilla Node.js, or use our [server plugins
 for **Fastify**, **Next.js**, and **Express**. We support Node.js v18.14.1 and later with
 the builtin `http` and `http2` modules.
 
+## Migrating from version 1
+
+Version 2 provides many new features and simplifies some common APIs. In addition, 
+it makes use of all the enhancements of Protobuf-ES v2. To upgrade, you'll need 
+to update your dependencies, re-generate code, and update call sites in your application.
+
+The first thing to be aware of is that the plugin `protoc-gen-connect-es` has been
+removed in v2. Connect now relies on descriptors generated by Protobuf-ES v2. 
+When upgrading, you will first need to remove any usage of this plugin. For most
+users, this means a combination of any of the following steps:
+
+* Remove `protoc-gen-connect-es` from their `package.json` either manually or
+  via a package manager, i.e. `npm uninstall @connectrpc/protoc-gen-connect-es`.
+
+* Remove any usage of the plugin in `buf.gen.yaml`.
+
+* Remove any dependency on Generated SDKs for Connect from `package.json` using
+  the same approach used for removing the plugin. Users should then rely on 
+  types from the `@bufbuild_es` plugin instead. This will also necessitate a code 
+  change, which is usually a simple import path update from *_connect to *_pb.
+
+Next, as mentioned, Connect uses Protobuf-ES v2, so you will need to upgrade any
+dependencies you have on its relevant packages:
+
+```shellsession
+npm install @bufbuild/protobuf@^2.0.0 @bufbuild/protoc-gen-es@^2.0.0
+```
+
+Finally, update the [packages](#packages) you use with your package manager of choice.
+For example, with NPM:
+
+```shellsession
+npm install @connectrpc/connect@^2.0.0 @connectrpc/connect-web@^2.0.0
+```
+
+### Update your code
+
+Next, you'll need to account for any breaking changes. Following is a list to
+be aware of:
+
+* `createGrpcTransport` now requires HTTP/2. 
+
+  If you are using `createGrpcTransport` and specifying an `httpVersion`, it will
+  now fail compilation. Remove the `httpVersion` property to use the default.
+  Note that if you were relying on HTTP/1.1 as part of your gRPC strategy, this
+  may require bigger architectural changes, but the hope is that this is not a
+  common problem.
+
+* The deprecated `createPromiseClient` has been removed.
+
+  Promise clients are now the default. Any callsites using `createPromiseClient`
+  should be updated to use `createClient`.
+
+* Node 16 is no longer supported.
+
+  Connect v2 now supports Node versions 18.14.1 and up.
+
+* Requests with similar shapes can no longer be used interchangeably. 
+
+  Previously, Connect allowed request objects with matching shapes to be passed
+  to API calls interchangeably as long as the passed object was a superset of the
+  target type. For example, given the following proto definitions:
+
+  ```protobuf
+  syntax = "proto3";
+  package example.v1;
+  message MessageA {
+    string field_a = 1;
+  }
+  message MessageB {
+    string field_a = 1;
+    int64 field_b = 2;
+  }
+  service ExampleService {
+    rpc RequestA(MessageA) returns (Empty) {}
+    rpc RequestB(MessageB) returns (Empty) {}
+  }
+  ```
+
+  The following would have passed TypeScript compilation:
+
+  ```ts
+  client.requestA(new MessageA())
+  client.requestA(new MessageB())
+  ```
+
+  This was an unintended bug and not a feature and in Connect v2, only the specified
+  target type will pass compilation.
+
+* `fetch`-related options `credentials` and `init` have been removed.
+
+  We have removed the `credentials` option from transports as well as the `init`
+  option in interceptors. These two options were used to customize `fetch` routines.
+  Users should now rely on the `fetch` option in transports as a way to perform
+  these customizations. For example:
+
+  ```ts
+  createConnectTransport({
+    baseUrl: "/",
+    fetch: (input, init) => fetch(input, {...init, credentials: "include"}),
+  });
+  ```
+
+  In addition, as a replacement to determine whether an incoming request is a 
+  Connect GET request in server-side interceptors, the property `requestMethod: string`
+  has been added to intercepted requests. This property is symmetrical to `HandlerContext.requestMethod`.
+
+* The access pattern of `MethodDescriptor` has slightly changed.
+
+  In v2, the Protobuf-ES plugin generates service descriptors and changes the 
+  access pattern for method descriptors. Instead of the plural form `methods`,
+  it now uses the singular `method`.
+
+  For example: `ElizaService.methods.Say` becomes `ElizaService.method.Say`.
+
+* Errors details are a pair of desc and init values
+
+  TBD
+
+* MethodDescriptor is self sufficient
+
+  TBD
+
+* Interceptors always use stream types
+
+  TBD
+
+
 ## Other platforms
 
 Would you like to use Connect on other platforms like Bun, Deno, Vercel’s Edge Runtime,