From c9fd0e55a414f6b3e86994337fc5edb4b7c5646c Mon Sep 17 00:00:00 2001 From: rybosome Date: Fri, 7 Apr 2017 16:36:34 -0700 Subject: [PATCH 1/4] Add annotations to specify GCP launch stage The Google Cloud Platform launch stage (https://cloud.google.com/terms/launch-stages) is a signifier of the level of access and support that can be expected of a particular feature. These annotations will be used to clearly demarcate features as being in a state other than General Availability to help set user expectations accordingly. --- .../java/com/google/cloud/GcpLaunchStage.java | 69 +++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 google-cloud-core/src/main/java/com/google/cloud/GcpLaunchStage.java diff --git a/google-cloud-core/src/main/java/com/google/cloud/GcpLaunchStage.java b/google-cloud-core/src/main/java/com/google/cloud/GcpLaunchStage.java new file mode 100644 index 000000000000..0a6e0621e383 --- /dev/null +++ b/google-cloud-core/src/main/java/com/google/cloud/GcpLaunchStage.java @@ -0,0 +1,69 @@ +/* + * Copyright 2016 Google Inc. All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package com.google.cloud; + +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; + +/** + * A qualifier indicating what level of access and support can be expected of a particualr Google + * Cloud Platform feature. The "GeneralAvailability" qualifier is not provided since the vast + * majority of features are in this category. + * + *

See more at the Launch Stages Documentation. + */ +public class GcpLaunchStage { + + /** + * Early Access features are limited to a closed group of testers. To use these features, you must + * sign up in advance and sign a Trusted Tester agreement (which includes confidentiality + * provisions). These features may be unstable, changed in backward-incompatible ways, and are not + * guaranteed to be released. + */ + @Retention(RetentionPolicy.SOURCE) + public @interface EarlyAccess {} + + /** + * Alpha is a limited availability test for releases before they are cleared for widespread use. + * By Alpha, all significant design issues are resolved and we are in the process of verifying + * functionality. Alpha customers need to apply for access, agree to applicable terms, and have + * their projects whitelisted. Alpha releases don’t have to be feature complete, no SLAs are + * provided, and there are no technical support obligations, but they will be far enough along + * that customers can actually use them in test environments or for limited-use tests -- just like + * they would in normal production cases. + */ + @Retention(RetentionPolicy.SOURCE) + public @interface Alpha {} + + /** + * Beta is the point at which we are ready to open a release for any customer to use. There are no + * SLA or technical support obligations in a Beta release, and charges may be waived in some + * cases. Products will be complete from a feature perspective, but may have some open outstanding + * issues. Beta releases are suitable for limited production use cases. + */ + @Retention(RetentionPolicy.SOURCE) + public @interface Beta {} + + /** + * Deprecated features are scheduled to be shut down and removed. For more information, see the + * “Deprecation Policy” section of our Terms of Service + * and the Google Cloud Platform Subject to the Deprecation Policy + * documentation. + */ + @Retention(RetentionPolicy.SOURCE) + public @interface Deprecated {} +} From 676a881d2cf054ee3762913e89ddd4815f0dede7 Mon Sep 17 00:00:00 2001 From: rybosome Date: Fri, 7 Apr 2017 16:56:12 -0700 Subject: [PATCH 2/4] Update the copyright date and make GcpLaunchStage a utility class --- .../src/main/java/com/google/cloud/GcpLaunchStage.java | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/google-cloud-core/src/main/java/com/google/cloud/GcpLaunchStage.java b/google-cloud-core/src/main/java/com/google/cloud/GcpLaunchStage.java index 0a6e0621e383..7c8d6935d86f 100644 --- a/google-cloud-core/src/main/java/com/google/cloud/GcpLaunchStage.java +++ b/google-cloud-core/src/main/java/com/google/cloud/GcpLaunchStage.java @@ -1,5 +1,5 @@ /* - * Copyright 2016 Google Inc. All Rights Reserved. + * Copyright 2017 Google Inc. All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -66,4 +66,8 @@ public class GcpLaunchStage { */ @Retention(RetentionPolicy.SOURCE) public @interface Deprecated {} + + private GcpLaunchStage() { + // Intentionally left blank. + } } From 319409e6990908401008774858d486f438542f9f Mon Sep 17 00:00:00 2001 From: rybosome Date: Mon, 10 Apr 2017 11:25:24 -0700 Subject: [PATCH 3/4] Change annotation retention to RUNTIME To ensure that this annotation will be easily visible to users and to grant the possibility of programmatic response to launch stage, this shouldn't only be a source-retained attribute. --- .../src/main/java/com/google/cloud/GcpLaunchStage.java | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/google-cloud-core/src/main/java/com/google/cloud/GcpLaunchStage.java b/google-cloud-core/src/main/java/com/google/cloud/GcpLaunchStage.java index 7c8d6935d86f..26207b0c4de7 100644 --- a/google-cloud-core/src/main/java/com/google/cloud/GcpLaunchStage.java +++ b/google-cloud-core/src/main/java/com/google/cloud/GcpLaunchStage.java @@ -34,7 +34,7 @@ public class GcpLaunchStage { * provisions). These features may be unstable, changed in backward-incompatible ways, and are not * guaranteed to be released. */ - @Retention(RetentionPolicy.SOURCE) + @Retention(RetentionPolicy.RUNTIME) public @interface EarlyAccess {} /** @@ -46,7 +46,7 @@ public class GcpLaunchStage { * that customers can actually use them in test environments or for limited-use tests -- just like * they would in normal production cases. */ - @Retention(RetentionPolicy.SOURCE) + @Retention(RetentionPolicy.RUNTIME) public @interface Alpha {} /** @@ -55,7 +55,7 @@ public class GcpLaunchStage { * cases. Products will be complete from a feature perspective, but may have some open outstanding * issues. Beta releases are suitable for limited production use cases. */ - @Retention(RetentionPolicy.SOURCE) + @Retention(RetentionPolicy.RUNTIME) public @interface Beta {} /** @@ -64,7 +64,7 @@ public class GcpLaunchStage { * and the Google Cloud Platform Subject to the Deprecation Policy * documentation. */ - @Retention(RetentionPolicy.SOURCE) + @Retention(RetentionPolicy.RUNTIME) public @interface Deprecated {} private GcpLaunchStage() { From f5b165ee92486739f8c4d9741f7f287644c96ac6 Mon Sep 17 00:00:00 2001 From: rybosome Date: Tue, 11 Apr 2017 12:32:37 -0700 Subject: [PATCH 4/4] Fix spelling and add qualifier --- .../src/main/java/com/google/cloud/GcpLaunchStage.java | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/google-cloud-core/src/main/java/com/google/cloud/GcpLaunchStage.java b/google-cloud-core/src/main/java/com/google/cloud/GcpLaunchStage.java index 26207b0c4de7..af4b951f34b1 100644 --- a/google-cloud-core/src/main/java/com/google/cloud/GcpLaunchStage.java +++ b/google-cloud-core/src/main/java/com/google/cloud/GcpLaunchStage.java @@ -20,9 +20,10 @@ import java.lang.annotation.RetentionPolicy; /** - * A qualifier indicating what level of access and support can be expected of a particualr Google + * A qualifier indicating what level of access and support can be expected of a particular Google * Cloud Platform feature. The "GeneralAvailability" qualifier is not provided since the vast - * majority of features are in this category. + * majority of features are in this category. Note that features may be in a later launch stage + * than the client library annotation indicates. * *

See more at the Launch Stages Documentation. */