docs: add recommendation to use v2.x and static discovery artifacts (#1434)
diff --git a/README.md b/README.md
index e5c8d36..334e1ec 100644
--- a/README.md
+++ b/README.md
@@ -16,10 +16,22 @@
[Client Libraries Explained](https://cloud.google.com/apis/docs/client-libraries-explained).
## Version 2.0 Release
-The 2.0 release of `google-api-python-client` is a significant upgrade compared
-to v1. Please see the [Migration Guide](https://github.com/googleapis/google-api-python-client/blob/master/UPGRADING.md) for more information.
-As a result of caching the discovery documents, the size of this package is at
-least 50 MB larger compared to the previous version.
+The 2.0 release of `google-api-python-client` includes a substantial reliability
+improvement, compared with 1.x, as discovery documents are now cached in the library
+rather than fetched dynamically. It is highly recommended to upgrade from v1.x to v2.x.
+
+Only python 3.6 and newer is supported. If you are not able to upgrade python, then
+please continue to use version 1.x as we will continue supporting python 2.7+ in
+[v1](https://github.com/googleapis/google-api-python-client/tree/v1).
+
+Discovery documents will no longer be retrieved dynamically when
+you call `discovery.build()`. The discovery documents will instead be retrieved
+from the client library directly. New versions of this library are released weekly.
+As a result of caching the discovery documents, the size of this package is at least
+50 MB larger compared to the previous version.
+
+Please see the [Migration Guide](https://github.com/googleapis/google-api-python-client/blob/master/UPGRADING.md)
+for more information.
## Documentation
diff --git a/UPGRADING.md b/UPGRADING.md
index 9ac0088..d1c60a9 100644
--- a/UPGRADING.md
+++ b/UPGRADING.md
@@ -1,35 +1,34 @@
# 2.0.0 Migration Guide
-The 2.0 release of `google-api-python-client` is a significant upgrade as only
-python 3.6 and newer is supported. If you are not able to upgrade python, then
+The 2.0 release of `google-api-python-client` includes a substantial reliability
+improvement, compared with 1.x, as discovery documents are now cached in the library
+rather than fetched dynamically. It is highly recommended to upgrade from v1.x to v2.x.
+
+Only python 3.6 and newer is supported. If you are not able to upgrade python, then
please continue to use version 1.x as we will continue supporting python 2.7+ in
[v1](https://github.com/googleapis/google-api-python-client/tree/v1).
-In addition, discovery documents will no longer be retrieved dynamically when
+Discovery documents will no longer be retrieved dynamically when
you call `discovery.build()`. The discovery documents will instead be retrieved
-from the client library directly. As a result of caching the discovery
-documents, the size of this package is at least 50 MB larger compared to the
-previous version.
+from the client library directly. New versions of this library are released weekly.
+As a result of caching the discovery documents, the size of this package is at least
+50 MB larger compared to the previous version.
For users of public APIs
------------------------
Existing code written for earlier versions of this library will not require
-updating. We believe this new default behaviour will provide a more predictable
-experience for users. If always using the latest version of a service definition
-is more important than reliability, users should set the `static_discovery`
-argument of `discovery.build()` to `False` to retrieve the service definition
-from the internet.
+updating.
For users of private APIs
-------------------------
-If the discovery document requires an authentication key to access it, the
+If the discovery document requires an authentication key to access it then the
discovery document is private and it will not be shipped with the library.
Only discovery documents listed in [this public directory](https://www.googleapis.com/discovery/v1/apis/)
are included in the library. Users of private APIs should set the
`static_discovery` argument of `discovery.build()` to `False` to continue to
retrieve the service definition from the internet. As of version 2.1.0,
-for backwards compatability with version 1.x, if `static_discovery` is not
+for backwards compatibility with version 1.x, if `static_discovery` is not
specified, the default value for `static_discovery` will be `True` when
the `discoveryServiceUrl` argument of `discovery.build()` is provided.
@@ -45,13 +44,12 @@
## Method Calls
**Note**: Existing code written for earlier versions of this library will not
-require updating. You should only update your code if always using the latest
-version of a service definition is more important than reliability or if you
-are using an API which does not have a public discovery document.
+require updating. You should only update your code if you are using an API
+which does not have a public discovery document.
> **WARNING**: Breaking change
-The 2.0.0 release no longer retrieves discovery documents dynamically on each
+The 2.0 release no longer retrieves discovery documents dynamically on each
call to `discovery.build()`. Instead, discovery documents are retrieved from
the client library itself.
@@ -78,7 +76,7 @@
with build('drive', 'v3') as service:
# ...
-# Retrieve discovery artifacts from the internet
-with build('drive', 'v3', static_discovery=False) as service:
+# Retrieve discovery artifacts from the internet for a private API
+with build('drive', 'v3', static_discovery=False, developerKey=XXXXX) as service:
# ...
```