Update README.md and docs root to clarify versioning

Fixes googleapis#618.
jskeet · Dec 6, 2016 · afe7b84 · afe7b84
1 parent 3053567
commit afe7b84
Show file tree

Hide file tree

Showing 2 changed files with 47 additions and 27 deletions.
diff --git a/README.md b/README.md
@@ -8,21 +8,26 @@
 * [Homepage](https://cloud.google.com/dotnet/)
 * [API Documentation](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/)
 
+The following libraries are available at a [late beta](#versioning) quality level:
 
-The Google Cloud Libraries for .NET support the following Google Cloud Platform services:
-
-* [Google BigQuery](https://cloud.google.com/bigquery/) - [API docs](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.BigQuery.V2/)
-* [Google Cloud Datastore](https://cloud.google.com/datastore/) - [API docs](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.Datastore.V1/)
-* [Stackdriver Logging](https://cloud.google.com/logging/) - [API docs](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.Logging.V2/)
-* Google Cloud Metadata - [API docs](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.Metadata.V1)
-* [Google Cloud Pub/Sub](https://cloud.google.com/pubsub/) - [API docs](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.PubSub.V1/)
-* [Google Cloud Storage](https://cloud.google.com/storage/) - [API docs](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.Storage.V1/)
-* [Google Cloud Vision](https://cloud.google.com/vision/) - [API docs](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.Vision.V1/)
-* [Google Cloud Natural Language](https://cloud.google.com/natural-language/) - [API docs](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.Language.V1Beta1/)
-* [Google Cloud Speech](https://cloud.google.com/speech/) - [API docs](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.Speech.V1Beta1/)
-* [Stackdriver Monitoring](https://cloud.google.com/monitoring/) - [API docs](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.Monitoring.V3/)
-* [Stackdriver Error Reporting](https://cloud.google.com/error-reporting/) - [API docs](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.ErrorReporting.V1Beta1/)
-* [Stackdriver Trace](https://cloud.google.com/trace/) - [API docs](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.Trace.V1/)
+* [Google Cloud Storage](https://cloud.google.com/storage/) - [API docs](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.Storage.V1/) (late beta)
+* [Google BigQuery](https://cloud.google.com/bigquery/) - [API docs](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.BigQuery.V2/) (late beta)
+* [Google Cloud Datastore](https://cloud.google.com/datastore/) - [API docs](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.Datastore.V1/) (late beta)
+* [Google Stackdriver Logging](https://cloud.google.com/logging/) - [API docs](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.Logging.V2/) (late beta)
+
+The following libraries are available at a [beta](#versioning) quality level:
+
+* [Google Cloud Pub/Sub](https://cloud.google.com/pubsub/) - [API docs](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.PubSub.V1/) (beta)
+* [Google Cloud Natural Language](https://cloud.google.com/natural-language/) - [API docs](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.Language.V1Beta1/) (beta)
+
+The following libraries are available at a [alpha](#versioning) quality level:
+
+* Google Cloud Metadata - [API docs](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.Metadata.V1) (alpha)
+* [Google Cloud Vision](https://cloud.google.com/vision/) - [API docs](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.Vision.V1/) (alpha)
+* [Google Cloud Speech](https://cloud.google.com/speech/) - [API docs](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.Speech.V1Beta1/) (alpha)
+* [Stackdriver Monitoring](https://cloud.google.com/monitoring/) - [API docs](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.Monitoring.V3/) (alpha)
+* [Stackdriver Error Reporting](https://cloud.google.com/error-reporting/) - [API docs](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.ErrorReporting.V1Beta1/) (alpha)
+* [Stackdriver Trace](https://cloud.google.com/trace/) - [API docs](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/Google.Cloud.Trace.V1/) (alpha)
 
 See the [API documentation](http://googlecloudplatform.github.io/google-cloud-dotnet/docs/) for details of the status
 of each library.
@@ -83,11 +88,27 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for more information on how to get star
 
 The Google Cloud Client Libraries for .NET follow [Semantic Versioning](http://semver.org/).
 
-Anything with a major version of zero (`0.y.z`) should not be
-considered stable - anything may change at any time.
-
-Anything with a suffix after the three numbers (such as `1.0.0-beta01`) is expected to work,
-but further API changes may occur before the next stable release.
+The version number in the package *name* (and .NET namespace)
+represents the version of the underlying API; the version number for
+the package itself indicates the status of the client library, according to
+the following quality levels:
+
+**Late Beta**: Libraries defined at a Beta quality level are
+expected to be mostly stable and we're working towards their release
+candidate. We will address issues and requests with a higher
+priority.
+
+**Beta**: Libraries defined at a Beta quality level are expected to
+be stable and working, but the API surface is still under active
+development. We encourage you to experiment with these libraries, but
+expect breaking changes in future versions. There may still be
+issues, but we have a fairly high degree of confidence.
+
+**Alpha**: Libraries defined at an Alpha quality level are still
+experimental. They may have significant issues, and the API surface
+will almost certainly change before a final release. We encourage
+experimentation with these libraries on test projects, but strongly
+discourage you from using them in a production environment.
 
 ## License
 

diff --git a/docs/root/index.md b/docs/root/index.md
@@ -14,25 +14,24 @@ supported here.
 
 ## APIs with supporting libraries
 
-Releases approaching general availability ("late stage beta"):
+Late beta:
 
 - [Google.Cloud.BigQuery.V2](Google.Cloud.BigQuery.V2/index.html)
 - [Google.Cloud.Datastore.V1](Google.Cloud.Datastore.V1/index.html)
 - [Google.Cloud.Logging.V2](Google.Cloud.Logging.V2/index.html)
 - [Google.Cloud.Storage.V1](Google.Cloud.Storage.V1/index.html)
 
-Alpha and beta releases from NuGet.org:
+Beta:
 
 - [Google.Cloud.Language.V1](Google.Cloud.Language.V1/index.html)
-- [Google.Cloud.Vision.V1](Google.Cloud.Vision.V1/index.html)
 - [Google.Cloud.PubSub.V1](Google.Cloud.PubSub.V1/index.html)
 
-Alpha releases from
-[MyGet](https://www.myget.org/gallery/google-dotnet-public):
+Alpha:
 
+- [Google.Cloud.ErrorReporting.V1Beta1](Google.Cloud.ErrorReporting.V1Beta1/index.html)
 - [Google.Cloud.Metadata.V1](Google.Cloud.Metadata.V1/index.html)
+- [Google.Cloud.Monitoring.V3](Google.Cloud.Monitoring.V3/index.html)
 - [Google.Cloud.Speech.V1Beta1](Google.Cloud.Speech.V1Beta1/index.html)
-- [Google.Devtools.AspNet](Google.Devtools.AspNet/index.html)
-- [Google.Cloud.ErrorReporting.V1Beta1](Google.Cloud.ErrorReporting.V1Beta1/index.html)
 - [Google.Cloud.Trace.V1](Google.Cloud.Trace.V1/index.html)
-- [Google.Cloud.Monitoring.V3](Google.Cloud.Monitoring.V3/index.html)
+- [Google.Cloud.Vision.V1](Google.Cloud.Vision.V1/index.html)
+- [Google.Devtools.AspNet](Google.Devtools.AspNet/index.html)