Add a migration guide #2199
Add a migration guide #2199
Conversation
Motivation: Moving from 1.x to 2.x isn't trivial. We should provide a guide for doing this. Modifications: - Add a guide for migrating client code and services - Add a script which can automate parts of this Result: Some guidance on migrating.
There was a problem hiding this comment.
Thanks for writing this up. I have a few questions here:
This seems to only outline a migration path for the simplest scenarios. What if an application author has multiple dependencies that use gRPC v1
- Do I have to wait until all of them vendored v1 so that I can depend on v2?
- If multiple dependencies vendor gRPC v1 then we should probably advise them rename/alias the modules otherwise we will have conflicts
dev/v1-to-v2/v1_to_v2.sh
Outdated
| # The path of the checkout. | ||
| grpc_checkout_path="${grpc_checkout_dir}/grpc-swift-v1" | ||
| # Version of grpc-swift to checkout. | ||
| grpc_v1_tag="1.24.2" |
There was a problem hiding this comment.
Would it be worth getting the latest tag by curling GH instead of hardcoding this here?
There was a problem hiding this comment.
Yeah, we can just look at the tags though.
dev/v1-to-v2/v1_to_v2.sh
Outdated
| -exec sed -i '' 's/protoc-gen-grpc-swift/protoc-gen-grpc-swift-v1/g' {} + | ||
|
|
||
| # Update the path of the protoc plugin so it aligns with the target name. | ||
| log "Updating direcotry name for protoc-gen-grpc-swift-v1" |
There was a problem hiding this comment.
| log "Updating direcotry name for protoc-gen-grpc-swift-v1" | |
| log "Updating directory name for protoc-gen-grpc-swift-v1" |
Sources/GRPCCore/Documentation.docc/Articles/Migration-guide.md
Outdated
Show resolved
Hide resolved
| upstream version of 2.x. | ||
| 2. Generate code for 2.x to alongside generated 1.x code. | ||
| 3. Incrementally migrate targets to 2.x. | ||
| 4. Remove the code generated for, and the dependency on 1.x. |
There was a problem hiding this comment.
| 4. Remove the code generated for, and the dependency on 1.x. | |
| 4. Remove the code generated for 1.x, and the dependency on 1.x. |
Sources/GRPCCore/Documentation.docc/Articles/Migration-guide.md
Outdated
Show resolved
Hide resolved
Sources/GRPCCore/Documentation.docc/Articles/Migration-guide.md
Outdated
Show resolved
Hide resolved
Sources/GRPCCore/Documentation.docc/Articles/Migration-guide.md
Outdated
Show resolved
Hide resolved
| is very similar, so you may not have to change any code. An important change to | ||
| highlight is that for RPCs which stream their responses you must handle the | ||
| response stream _within_ the closure passed to the client. By way of example, | ||
| imagine the following server streaming RPC from 1.x: |
There was a problem hiding this comment.
Might also be helpful to link to appropriate tutorials/examples/docs from here?
There was a problem hiding this comment.
I'm not sure what would be useful beyond the inline examples?
There was a problem hiding this comment.
Okay fair, I was thinking it would be nice to have a link to the rest of the docs but this will likely be read in the context of the whole documentation anyways so finding the other docs should be easy.
The guide doesn't recommend that you keep the copy of v1. Indeed step 4 of the overview is to remove the copy of v1; It's only there to minimise the number of compilation errors during migration (this is also mentioned in the overview). |
Sources/GRPCCore/Documentation.docc/Articles/Migration-guide.md
Outdated
Show resolved
Hide resolved
| is very similar, so you may not have to change any code. An important change to | ||
| highlight is that for RPCs which stream their responses you must handle the | ||
| response stream _within_ the closure passed to the client. By way of example, | ||
| imagine the following server streaming RPC from 1.x: |
There was a problem hiding this comment.
Okay fair, I was thinking it would be nice to have a link to the rest of the docs but this will likely be read in the context of the whole documentation anyways so finding the other docs should be easy.
Co-authored-by: Gus Cairo <[email protected]>
Motivation:
Moving from 1.x to 2.x isn't trivial. We should provide a guide for doing this.
Modifications:
Result:
Some guidance on migrating.