Round 2

MIGRATING.md

@@ -1,12 +1,11 @@
-# Migration Guide
-
-## Migrating from version 1 to version 2
+# Connect v1 to v2 migration guide
 
 Connect v2 provides new features and simplifies some common APIs. In addition,
-it makes use of all the enhancements of Protobuf-ES v2. This document walks you
-through all you need to know.
+it makes use of all the enhancements of Protobuf-ES v2. If you're currently 
+using Connect v1, this document walks you through all you need to know to migrate
+and start using it right away.
 
-### Migrating your code
+## Running the migration tool
 
 To help with the process of migrating, we provide a tool called 
 [@connectrpc/connect-migrate](https://www.npmjs.com/package/@connectrpc/connect-migrate) 
@@ -18,36 +17,35 @@ execute the following command:
 
 While the tool will do a lot of the dependency legwork for you, there are many
 use cases in code that it does not cover. Below, we list everything that has changed in 
-v2 and whether it is fixed by the migration tool or whether it will require 
-manual intervention.
+v2. Changes that are handled by the migration tool are noted as such.
 
 In summary, the suggested way to migrate to Connect v2 is to first run the migration tool
 and then go through the list below, fixing any other instances that weren't handled.
 
-### Updating dependencies
+## What's changed
+
+### Dependency updates
 
 Perhaps the biggest thing to be aware of is that the plugin `protoc-gen-connect-es` has been
 removed in v2. Connect now relies on service descriptors generated by the Protobuf-ES v2
 `protoc-gen-es` and no longer generates code itself.
 
 So the first major part of the migration path is removing any usage of the old 
-`protoc-gen-connect-es` plugin. This means a combination of any 
-of the following:
+`protoc-gen-connect-es` plugin. This could include:
 
 - Removing `protoc-gen-connect-es` from `package.json`.
-
 - Removing any usage of the plugin in `buf.gen.yaml`.
-
 - Removing any dependency on Generated SDKs for Connect from `package.json`.
 
-Next, upgrade any dependencies on [Protobuf-ES packages](https://github.com/bufbuild/protobuf-es?tab=readme-ov-file#packages)  
+The next step is to upgrade any dependencies on [Protobuf-ES packages](https://github.com/bufbuild/protobuf-es?tab=readme-ov-file#packages)  
 to use v2.
 
-Finally, update the Connect [packages](#packages) in your project to use v2.
+The final step is to update the Connect [packages](#packages) in your project 
+to use v2.
 
 :white_check_mark: The `connect-migrate` tool will handle all of these changes.
 
-### Generate code
+### Generated code
 
 The next step is to re-generate code. The migration tool does not handle code
 generation, so be sure to do so in whatever way your project is configured. For
@@ -71,7 +69,7 @@ introduced in v1.36.0. See the docs [here](https://buf.build/docs/configuration/
 for specifying `clean` in your config files. Note that you can also specify `--clean`
 to any `buf generate` CLI commands you are running.
 
-### Update import paths
+### Import paths
 
 Once your code is generated and the vestigial `*_connect` files are removed, 
 import paths should be updated. This is usually an update from `*_connect` to
@@ -84,8 +82,7 @@ import paths should be updated. This is usually an update from `*_connect` to
 
 :white_check_mark: The `connect-migrate` tool will handle this.
 
-
-### Update usages with generated code
+### Working with generated code
 
 As mentioned, Connect now solely uses the `protoc-gen-es` plugin provided by  
 Protobuf-ES v2. As a result, working with generated code has changed in some
@@ -114,8 +111,7 @@ Connect now relies on service descriptors generated by the Protobuf-ES v2
 the service descriptors previously generated by Connect v1. The same basic 
 information i.e. (typed metadata) is still generated, but it's generated by 
 `protoc-gen-es` now, along with additional information available. For example, 
-the generated code in v2 now provides the full descriptor, with 
-features such as [custom options](https://github.com/bufbuild/protobuf-es/blob/v2.2.2/MANUAL.md#custom-options), 
+v2 now provides the full descriptor, with features such as [custom options](https://github.com/bufbuild/protobuf-es/blob/v2.2.2/MANUAL.md#custom-options), 
 which can be very useful in interceptors.
 
 One breaking change to be aware with service descriptors is that the access 
@@ -159,6 +155,8 @@ dot notation is used. However, a few noteworthy changes to be aware of:
   a property `$typeName`, which is a simple string with the full name of
   the message like `"example.User"`. This property makes sure you don't pass the 
   wrong message to a function by accident.
+* The `PartialMessage` type has been mostly replaced by `MessageInitShape`, which 
+  extracts the init type from a message descriptor.
 * A message field using [`google.protobuf.Struct`](https://github.com/bufbuild/protobuf-es/blob/main/MANUAL.md#googleprotobufstruct) 
   is now generated as more-convenient `JsonObject`.
 * `proto2` fields with default values are no longer generated as optional 
@@ -167,8 +165,8 @@ dot notation is used. However, a few noteworthy changes to be aware of:
   `@bufbuild/protobuf/wkt`. For example, when converting a `google.protobuf.Timestamp` 
   to an ECMAScript Date object, it is no longer possible via a method. 
 
-For more information on all Protobuf-ES v2 changes, see the 
-[Protobuf-ES v2 migration guide](https://github.com/bufbuild/protobuf-es/blob/main/MANUAL.md#update-your-code).
+For more information on all Protobuf-ES v2 changes, see the Protobuf-ES [manual](https://github.com/bufbuild/protobuf-es/blob/main/MANUAL.md)
+as well as the [Protobuf-ES v2 migration guide](https://github.com/bufbuild/protobuf-es/blob/main/MANUAL.md#update-your-code).
 
 ### Other breaking changes