-
Notifications
You must be signed in to change notification settings - Fork 81
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add migration guide for v2 #1327
Conversation
7c85665
to
f0a772e
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
WDYT about moving this to a separate markdown file? A year down the road, we probably don't want to have the guide take real estate on the main README, but it would be good to have stable links. A separate file would solve this.
Other changes users are likely to run into:
- When creating a message to pass in a request field, the syntax changes quite a bit. It's common outside of simple examples, so we have to show an example.
- If you use a BSR dependency for custom options, generated code will reference it. This means you have to generate with
include_imports: true
. A good example is any message that uses protovalidate. - PlainMessage - we can repeat the information from the Protobuf-ES migration guide.
- WKT methods - for example, converting a
google.protobuf.Timestamp
to an ECMAScript Date object is no longer possible via a method. We need to call out the helpers exported from@bufbuild/protobuf/wkt
, because they are not easily discoverable. Similar for google.protobuf.Any.
Also notable:
- In general, request and responses do not need any changes when initializers / dot notation is used, but
google.protobuf.Struct
is now generated as a more convenientJsonObject
, and proto2 fields with default values are no longer generated as optional properties. - SSR is generally much more simple because it doesn't require any extra steps (with proto3). This is difficult to explain in all details with a diff, but we really need to explain the general changes.
Just noticed: We also need to call out: |
One thing I noticed with my migration in the BSR is that the usage of helper types like
Not exactly sure where to put those but feels like we should mention them. |
29bf18b
to
d65b84f
Compare
OK, I think I incorporated everything into this round 2 of changes. The only thing I didn't add is the bit about SSR since that isn't really a migration change. @timostamm let me know where you think it fits best (or if it makes more sense to just link to connect docs for SSR) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice! Left a couple of suggestions below.
the bit about SSR
I think we do need examples for how SSR changes, and guidance for replacing usage of PlainMessage
and PartialMessage
. But we can do that in a separate PR.
@timostamm ready for round 3. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM!
Took a note to look into better guidance for PlainMessage and PartialMessage and to add examples for SSR.
Signed-off-by: Steve Ayers <sayers@buf.build>
Signed-off-by: Steve Ayers <sayers@buf.build>
543394a
to
d2acd07
Compare
This adds a guide to the main README for migrating from Connect v1 to Connect v2.