v3: add migration helpers and guide for breaking changes

[tswast]

I'd like to make sure we don't get folks stuck on v2. I know we have some internal (Google) customers who rely on the BQML stats protobuf messages (the ones in google.cloud.bigquery_v2.

I propose

1. We restore the files in google.cloud.bigquery_v2, but document that they are deprecated and are not updated.
2. We continue to return dictionaries in the relevant classes, so that all stays the same.
3. We document in the UPGRADING guide how to manually convert from the dictionaries to the classes in google.cloud.bigquery_v2 with some code samples.

Regarding the pandas connector changes, we should also document those in the UPGRADING guide, ideally with code samples on how to get / convert to the old dtypes if desired.

[tswast]

@plamut Does this make sense? I want to keep the changes we've made and avoid using/updating the bigquery_v2 code in the client, but the type classes can still be available so that folks can migrate to dictionary-style access at their own pace.

[plamut]

We restore the files in google.cloud.bigquery_v2, but document that they are deprecated and are not updated.

How is that supposed to work, just keeping those type classes around so that one can import them if really needed? But otherwise no compatibility logic and no direct exposure in the top level namespace google.cloud.bigquery? In other words, the users will be entirely responsible for converting these classes to/from dicts?

Re: conversions - we'll probably recommend protobuf.json_format for that, and presumably users will have to install that dependency manually?

With these assumptions, I think it could work fine with minimal overhead, yes. As a bonus, we could also issue a runtime warning if anything is imported from the bigquery_v2 namespace.

Edit: Will we also keep the v2 type classes in the reference docs? Noticed this aspect when resolving a merge conflict on the v2 removal PR.

[tswast]

That's right. Just keep the autogenerated classes around and show folks how to parse JSON. Probably with a code sample for what we used to do that ignored unknown enums and such, especially since we don't plan to keep the type classes updated.

As a bonus, we could also issue a runtime warning if anything is imported from the bigquery_v2 namespace.

That's a great idea.

Edit: Will we also keep the v2 type classes in the reference docs? Noticed this aspect when resolving a merge conflict on the v2 removal PR.

Yes, let's keep them in the docs and add a deprecation warning.

[plamut]

Looking at #855 and how large it is, it IMO makes sense to do this in a separate PR after that large PR has been merged.

[meredithslota]

Closed in #888 and #1027.