@google-cloud/compute breaking changes in v3 is undocumented and new ref docs is incomplete and confusing

[evil-shrike]

The v3 version of @google-cloud/compute is devastating, it has a completely different API. And there's no any description anywhere about this.
The homepage for the library - https://cloud.google.com/nodejs/docs/reference/compute/latest - contains a line "A comprehensive list of changes in each version may be found in the CHANGELOG". But the link to CHANGELOG is broken (404).
But even if we manage to find it on https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-compute/CHANGELOG.md it contains just one line: "new generated version of compute API (#537)" and that's all!
Not very comprehensive isn't it?
How do you see people will migrate existing code?

I won't discuss the new API itself but you should at least have released a consistent API reference for it. But these two sites have quite different content about the same new API:

• https://googleapis.dev/nodejs/compute/latest/v1.InstancesClient.html
• https://cloud.google.com/nodejs/docs/reference/compute/latest/compute/v1.instancesclient

All links to samples on googleapis.dev/nodejs/compute are all broken.

If we take the cloud.google.com/nodejs/docs/reference as the source of truth and try to use for such a simple task as creating a VM (which was as simple as compute.zone(zoneName).createVM(vmName, vmConfig) with the old API) we'll quickly find it's very confusing. The only sample is
https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-compute/samples/generated/v1/instances.insert.js
but it tell nothing! What's the instanceResource?

Ok, you go to the ref doc to find out - the method doc has unclickable type reference protos.google.cloud.compute.v1.IInsertInstanceRequest. Where should I find it? After a while I found the list of types on the Overview (what?) page, and went to the type description page - https://cloud.google.com/nodejs/docs/reference/compute/latest/compute/protos.google.cloud.compute.v1.iinsertinstancerequest
That InsertInstanceRequest has a field of type google.cloud.compute.v1.IInstance which again I should look up via Overview page because links are not working.

The funny thing that right after the new version had been released, it was in the old repo nodejs-compute and it did have a decent sample - samples/createInstance.js - https://github.com/googleapis/nodejs-compute/blob/4023676e121e3b3c71b681dbd77136ab74184e68/samples/createInstance.js

Why didn't you move it to the new repo?

In the end, I'd say ref doc and samples require more efforts to make them consistent and easy to use. Samples should demonstrate some particular use-case. If it's creating a VM I should be able to use for creating a VM. Current it demonstrates nothing.
The should a specific place/article/page for describing the API change, why it happens and what's main ideas behind the new design, where and how I should migrate my code (if at all), and so on.

[bcoe]

But even if we manage to find it on https://github.com/googleapis/google-cloud-node/blob/main/packages/google-cloud-compute/CHANGELOG.md it contains just one line: "new generated version of compute API (#537)" and that's all!
Not very comprehensive isn't it? How do you see people will migrate existing code?

I agree this is not ideal.

When we migrated from 2.x to 3.x a year ago, we made the decision that the API was so different in 3.x that we would not enumerate all of the differences. At the time, we also decided to not write an upgrade guide, instead putting our time mostly into updating samples.

We also intended to keep a close eye on any issues that were opened at time of launch. If we'd seen an influx of user issues, or internal escalations, we would have course corrected by adding a migration guide, additional samples, etc.

I agree that this plan was too reactive, and it would have been a better experience out of the if we'd had a migration guide.

Having said this, we did not see an influx of many user issues post-launch, and our usage #s on 3.x of the library are now ~5x vs., that of 2.x.

I won't discuss the new API itself but you should at least have released a consistent API reference for it. But these two sites have quite different content about the same new API:

@dansaadati is in the process of deprecating the reference documentation on googleapis.dev (cloud.google.com will be the source of truth).

I've shared this thread with the @dansaadati's team, I agree we need to make the reference documentation better for complex types like protos.google.cloud.compute.v1.IInsertInstanceRequest.

The funny thing that right after the new version had been released, it was in the old repo nodejs-compute and it did have a decent sample - samples/createInstance.js

We're guilty of shipping our org chart. When we migrated libraries into the mono-repo, we migrated samples into a separate samples mono-repo (they can be found here).

In itself, I don't think this is a problem, but we need to better cross-link between the two repositories. It should be easy for a customer who lands in either repository to understand the relationship between the samples and the client library.

@alexander-fenster, @sofisl, let's make sure we capture this work in a feature request? @evil-shrike outlines a customer user journey that isn't great.

[evil-shrike]

Hi @bcoe,
thanks for the reply,
leaving aside all the hassle with new version,
why at least not to put links to existing sources in https://github.com/GoogleCloudPlatform/nodejs-docs-samples/tree/main/compute, which you mentioned, into the README of the root project on https://github.com/googleapis/google-cloud-node/tree/main/packages/google-cloud-compute?
Currently the README refers to autogenerated samples which are not very helpful. And this confuses a lot.

Regarding a migration guide, well, probably anyway it's too late, but it's be nice to understand the correlation between client library versions (2.x and 3.x) and the API itself. At least whether it's safe to use 2.x and for how long (technically it's working). So users (including internal ones) could understand whether we have to migrate and what are deadlines for this (if at all).

Thanks.

[sofisl]

@evil-shrike, thanks so much for taking the time to give us this feedback - it's very helpful! There were a few issues that I got from this writeup, please see below:

• google.cloud.com's publishing was broken due to the monorepo migration. This was fixed here
• googleapis.dev had also been broken during the migration. This was fixed here
• all new docs were re-run and published in this release (confirmed that docs are up-to-date)
• The README needed to contain new links in the migration, fixed here and here

Future work:

• Possibly making clickable type references? (@dansaadati perhaps?)
• Linking to nodejs-docs-samples handwritten samples in the main README, as well as in Compute itself.

Feel free to add to this if you think something is missing, but if not, thanks again for writing up your feedback.