3 ms·

Reasoning went something like this: We could tag the new API v2: + Makes the "v1" and "v2" distinction very clear in the import path. - Confusing: google.gol

by neild 7y ago

Reasoning went something like this: We could tag the new API v2: + Makes the "v1" and "v2" distinction very clear in the import path. - Confusing: google.golang.org/protobuf@v1 doesn't exist, but v2 does. - In ten years, hopefully nobody cares about the old github.com/golang/protobuf and the confusion is gone. We could tag the new API v1: - Less visually distinct in the import path. + Seems to make sense for the first version of google.golang.org/protobuf to be a v1. + If we decide it was a terrible idea, it's easier to go from v1 to v2 than to roll back from v2 to v1. We waffled back and forth for quite a while on this, and eventually decided that the first version of google.golang.org/protobuf would be a v1. Then as we got closer to release (but with a certain amount of usage of v0 in the wild), we decided not to second-guess that decision but to start with a version that wouldn't overlap with any version of github.com/golang/protobuf to avoid confusion when someone reports a bug in "v1.0.1". Maybe it was the wrong choice. If it was the worst choice we've made in the new API, I'll be happy!

farslan 7y ago
Thanks for the all the work. And I hope my rant doesn't come something as a bad. But I truly believe the versioning along with the import path is confusing. I hope the team goes over the versioning again and come up with something that makes more sense.
llimllib 7y ago
When I read the article, my brain passed right over the different domain names; the two are even the exact same number of characters, set in a monospace font, and my brain passes right over the domain of golang imports to the end of the path. That's where the interesting bit is (usually!) I find this a super confusing and unintuitive choice, but I suppose it's too late for changing it now. Sincerely, an othwerwise mostly happy protobuf user
rverghese 7y ago
What are you going to do for APIv3? Version it as google.golang.org@v2? google.golang.org@v3 (but @v2 doesn't exist)? Release an @v2 which is identical to @v1?
- neild 7y ago
  We used up our breaking change budget for the next decade with this release, so we'll think about it in 2030.
  - deleted 7y ago
    [deleted]
  - loopz 7y ago
    Admit it, once Windows 22 is out the door, protobuf 1.22 is shippin' as well! Yieehaaw! Rust .22 with breaking changes, will be breaking 4 years after that as well!
bouk 7y ago
You could give google.golang.org/protobuf@v1 an //importpath to the github package, so go would warn people about it.
tsimionescu 7y ago
> The google.golang.org/protobuf module is APIv2. We have taken advantage of the need to change the import path to switch to one that is not tied to a specific hosting provider. This seems like a good example why tying the name of the package in the code with the place where it can be downloaded was a very bad idea. Simply changing hosting providers is now a backwards compatibility break for your clients. If Go imports didn't work this way, you could have simply offered the old v1 from both github.com and google.golang.org, and used a clear v2 for the v2. Sure , you would have similar problems if you wanted to change the logical package structure for some reason (say, when an open-source package moves to a different organization), but that is a much rarer case than switching code repos. However, given that that ship has probably long sailed, you probably picked the right choice. I would also note that v2 in the import path feels a bit strange, since it makes users of the newest code need to know about the history of the package, but there are also clear advantages which probably out-weigh this (I believe this is absolutely not the case for the decision to include the hosting provider in the import path).
- neild 7y ago
  Indeed, tying the name of a package to a hosting provider is a bad idea! That's why we changed to an import path which isn't tied to one. google.golang.org/protobuf is not tied to any particular provider, and we can redirect it wherever we want. See "go help importpath" for details on how this works.
  - randallsquared 7y ago
    > - Confusing: google.golang.org/protobuf@v1 doesn't exist, but v2 does. > google.golang.org/protobuf is not tied to any particular provider, and we can redirect it wherever we want. I agree, this is confusing. Why doesn't google.golang.org/protobuf@v1 return what's at github.com/golang/protobuf, then, if only to provide a tidy answer for those who wonder what v1 looked like?
    - tsimionescu 7y ago
      Because the Go package name is github.com/golang/protobuf. Serving it from a different address is already a breaking change.
rolleiflex 7y ago
I think you’re overestimating how much people pay attention to the body part of the import paths. Since there have been a quite few projects that implemented a sort of redirect (i.e. ‘vanity’ imports [0]) most people’s eyes just glaze over the small change in the URL. I would strongly suggest using /v2 at the end. /v1 not existing on *.golang.org is not a problem in practice, but if it ends up one you could just set that up as a vanity import pointing to github.com for the old version. [0] https://sagikazarmark.hu/blog/vanity-import-paths-in-go/ https://sagikazarmark.hu/blog/vanity-import-paths-in-go/
iainmerrick 7y ago
When you were waffling back on forth on the decision, did anyone note that “re-using v1 is a weird choice and is going to be the main thing people talk about”?
SoylentOrange 7y ago
Can you explain why it's not possible to create `google.golang.org/protobuf@v1` retroactively? Also: > In ten years, hopefully nobody cares about the old github.com/golang/protobuf and the confusion is gone. is the corollary that this change will cause 10 years of confusion?
amptorn 7y ago
> - Confusing: google.golang.org/protobuf@v1 doesn't exist, but v2 does. This would not be confusing at all. The UUID package I use just skipped from major version 3 to major version 7 to avoid confusion with UUIDv4, UUIDv5 and a possibe UUIDv6. It was well-documented, and even if it wasn't, the upgrade was absolutely painless, as it would have been either way.

by neild 7y ago

farslan 7y ago

Thanks for the all the work. And I hope my rant doesn't come something as a bad. But I truly believe the versioning along with the import path is confusing. I hope the team goes over the versioning again and come up with something that makes more sense.

llimllib 7y ago

When I read the article, my brain passed right over the different domain names; the two are even the exact same number of characters, set in a monospace font, and my brain passes right over the domain of golang imports to the end of the path. That's where the interesting bit is (usually!) I find this a super confusing and unintuitive choice, but I suppose it's too late for changing it now. Sincerely, an othwerwise mostly happy protobuf user

rverghese 7y ago

What are you going to do for APIv3? Version it as google.golang.org@v2? google.golang.org@v3 (but @v2 doesn't exist)? Release an @v2 which is identical to @v1?

neild 7y ago
We used up our breaking change budget for the next decade with this release, so we'll think about it in 2030.
- deleted 7y ago
  [deleted]
- loopz 7y ago
  Admit it, once Windows 22 is out the door, protobuf 1.22 is shippin' as well! Yieehaaw! Rust .22 with breaking changes, will be breaking 4 years after that as well!

bouk 7y ago

You could give google.golang.org/protobuf@v1 an //importpath to the github package, so go would warn people about it.

tsimionescu 7y ago

> The google.golang.org/protobuf module is APIv2. We have taken advantage of the need to change the import path to switch to one that is not tied to a specific hosting provider. This seems like a good example why tying the name of the package in the code with the place where it can be downloaded was a very bad idea. Simply changing hosting providers is now a backwards compatibility break for your clients. If Go imports didn't work this way, you could have simply offered the old v1 from both github.com and google.golang.org, and used a clear v2 for the v2. Sure , you would have similar problems if you wanted to change the logical package structure for some reason (say, when an open-source package moves to a different organization), but that is a much rarer case than switching code repos. However, given that that ship has probably long sailed, you probably picked the right choice. I would also note that v2 in the import path feels a bit strange, since it makes users of the newest code need to know about the history of the package, but there are also clear advantages which probably out-weigh this (I believe this is absolutely not the case for the decision to include the hosting provider in the import path).

neild 7y ago
Indeed, tying the name of a package to a hosting provider is a bad idea! That's why we changed to an import path which isn't tied to one. google.golang.org/protobuf is not tied to any particular provider, and we can redirect it wherever we want. See "go help importpath" for details on how this works.
- randallsquared 7y ago
  > - Confusing: google.golang.org/protobuf@v1 doesn't exist, but v2 does. > google.golang.org/protobuf is not tied to any particular provider, and we can redirect it wherever we want. I agree, this is confusing. Why doesn't google.golang.org/protobuf@v1 return what's at github.com/golang/protobuf, then, if only to provide a tidy answer for those who wonder what v1 looked like?
  - tsimionescu 7y ago
    Because the Go package name is github.com/golang/protobuf. Serving it from a different address is already a breaking change.

rolleiflex 7y ago

I think you’re overestimating how much people pay attention to the body part of the import paths. Since there have been a quite few projects that implemented a sort of redirect (i.e. ‘vanity’ imports [0]) most people’s eyes just glaze over the small change in the URL. I would strongly suggest using /v2 at the end. /v1 not existing on *.golang.org is not a problem in practice, but if it ends up one you could just set that up as a vanity import pointing to github.com for the old version. [0] https://sagikazarmark.hu/blog/vanity-import-paths-in-go/ https://sagikazarmark.hu/blog/vanity-import-paths-in-go/

iainmerrick 7y ago

When you were waffling back on forth on the decision, did anyone note that “re-using v1 is a weird choice and is going to be the main thing people talk about”?

SoylentOrange 7y ago

Can you explain why it's not possible to create `google.golang.org/protobuf@v1` retroactively? Also: > In ten years, hopefully nobody cares about the old github.com/golang/protobuf and the confusion is gone. is the corollary that this change will cause 10 years of confusion?

amptorn 7y ago

> - Confusing: google.golang.org/protobuf@v1 doesn't exist, but v2 does. This would not be confusing at all. The UUID package I use just skipped from major version 3 to major version 7 to avoid confusion with UUIDv4, UUIDv5 and a possibe UUIDv6. It was well-documented, and even if it wasn't, the upgrade was absolutely painless, as it would have been either way.