docs: Distinguish between public/private docs in 2.0 guide (#1226)
Fixes #1225 🦕
diff --git a/UPGRADING.md b/UPGRADING.md
index 475bd9f..c3c9171 100644
--- a/UPGRADING.md
+++ b/UPGRADING.md
@@ -7,11 +7,24 @@
In addition, 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. 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
+from the client library directly.
+
+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.
+
+For users of private APIs
+-------------------------
+If the discovery document requires an authentication key to access it, 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.
If you experience issues or have questions, please file an [issue](https://github.com/googleapis/google-api-python-client/issues).
@@ -27,7 +40,8 @@
**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.
+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.
> **WARNING**: Breaking change