cleanup(spanner): deprecate legacy Spanner admin interfaces (#7359)

Start the one-year deprecation clock on the legacy, hand-written Spanner admin interfaces. Also bump the `disable_deprecation_warnings.inc` include-ordering priority. In general, it needs to appear before any other inclusions. See #7356.
googleapis · Sep 25, 2021 · 721d690 · 721d690
1 parent 801f24a
commit 721d690
Show file tree

Hide file tree

Showing 23 changed files with 65 additions and 7 deletions.
diff --git a/.clang-format b/.clang-format
@@ -10,6 +10,8 @@ PointerAlignment: Left
 IncludeBlocks: Merge
 IncludeCategories:
 # Matches common headers first, but sorts them after project includes
+- Regex: '^\"google/cloud/internal/disable_deprecation_warnings.inc\"$'
+  Priority: -1
 - Regex: '^\"google/cloud/(internal/|grpc_utils/|testing_util/|[^/]+\.h)'
   Priority: 1000
 - Regex: '^\"google/cloud/'  # project includes should sort first

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -52,6 +52,21 @@
   the call site. See [#5929] for more details.
 </details>
 
+<details>
+<summary>2022-10-01: retiring legacy Spanner admin APIs</summary>
+<br>
+
+* On 2022-10-01 (or shortly after) we are planning to remove the hand-written
+  versions of the Spanner admin APIs. These have been superseded by versions
+  generated automatically from the service definitions. The new APIs can be
+  found in the [`google/cloud/spanner/admin`](https://github.com/googleapis/google-cloud-cpp/tree/main/google/cloud/spanner/admin)
+  tree and within the `google::cloud::spanner_admin` namespace. Starting with
+  the v1.32.0 release, and depending on your compiler settings, using these
+  classes/functions may elicit a deprecation warning. See
+  [#7356](https://github.com/googleapis/google-cloud-cpp/issues/7356) for more
+  details.
+</details>
+
 ## v1.32.0 - TBD
 
 ### [Storage](https://github.com/googleapis/google-cloud-cpp/blob/main/google/cloud/storage/README.md)

diff --git a/ci/cloudbuild/builds/publish-docs.sh b/ci/cloudbuild/builds/publish-docs.sh
@@ -24,7 +24,7 @@ doc_args=(
   "-DCMAKE_BUILD_TYPE=Debug"
   "-DGOOGLE_CLOUD_CPP_GENERATE_DOXYGEN=ON"
   "-DGOOGLE_CLOUD_CPP_GEN_DOCS_FOR_GOOGLEAPIS_DEV=ON"
-  "-DDOXYGEN_CLANG_OPTIONS=-resource-dir=$(clang -print-resource-dir)"
+  "-DDOXYGEN_CLANG_OPTIONS=-resource-dir=$(clang -print-resource-dir) -Wno-deprecated-declarations"
 )
 
 # Extract the version number if we're on a release branch.

diff --git a/cmake/GoogleCloudCppCommon.cmake b/cmake/GoogleCloudCppCommon.cmake
@@ -79,6 +79,7 @@ elseif (GOOGLE_CLOUD_CPP_GENERATE_DOXYGEN)
         "GOOGLE_CLOUD_CPP_DEPRECATED(x)="
         "GOOGLE_CLOUD_CPP_IAM_DEPRECATED(x)="
         "GOOGLE_CLOUD_CPP_BIGTABLE_IAM_DEPRECATED(x)="
+        "GOOGLE_CLOUD_CPP_SPANNER_ADMIN_API_DEPRECATED(x)="
         "GOOGLE_CLOUD_CPP_GENERATED_NS=v${PROJECT_VERSION_MAJOR}"
         "GOOGLE_CLOUD_CPP_NS=v${PROJECT_VERSION_MAJOR}"
         "GOOGLE_CLOUD_CPP_PUBSUB_NS=v${PROJECT_VERSION_MAJOR}"

diff --git a/generator/integration_tests/golden/tests/.clang-format b/generator/integration_tests/golden/tests/.clang-format
@@ -10,6 +10,8 @@ PointerAlignment: Left
 IncludeBlocks: Merge
 IncludeCategories:
 # Matches common headers first, but sorts them after project includes
+- Regex: '^\"google/cloud/internal/disable_deprecation_warnings.inc\"$'
+  Priority: -1
 - Regex: '^\"google/cloud/(internal/|grpc_utils/|testing_util/|[^/]+\.h)'
   Priority: 1000
 - Regex: '^\"google/cloud/'  # project includes should sort first

diff --git a/google/cloud/spanner/database_admin_client.cc b/google/cloud/spanner/database_admin_client.cc
@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// TODO(#7356): Remove this file after the deprecation period expires
+#include "google/cloud/internal/disable_deprecation_warnings.inc"
 #include "google/cloud/spanner/database_admin_client.h"
 #include "google/cloud/spanner/timestamp.h"
 #include <algorithm>

diff --git a/google/cloud/spanner/database_admin_client.h b/google/cloud/spanner/database_admin_client.h
@@ -114,7 +114,8 @@ inline namespace SPANNER_CLIENT_NS {
  * [database-doc-link]:
  * https://cloud.google.com/spanner/docs/schema-and-data-model
  */
-class DatabaseAdminClient {
+class GOOGLE_CLOUD_CPP_SPANNER_ADMIN_API_DEPRECATED("DatabaseAdminClient")
+    DatabaseAdminClient {
  public:
   explicit DatabaseAdminClient(
       ConnectionOptions const& options = ConnectionOptions());

diff --git a/google/cloud/spanner/database_admin_client_test.cc b/google/cloud/spanner/database_admin_client_test.cc
@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// TODO(#7356): Remove this file after the deprecation period expires
+#include "google/cloud/internal/disable_deprecation_warnings.inc"
 #include "google/cloud/spanner/database_admin_client.h"
 #include "google/cloud/spanner/mocks/mock_database_admin_connection.h"
 #include "google/cloud/spanner/timestamp.h"

diff --git a/google/cloud/spanner/database_admin_connection.cc b/google/cloud/spanner/database_admin_connection.cc
@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// TODO(#7356): Remove this file after the deprecation period expires
+#include "google/cloud/internal/disable_deprecation_warnings.inc"
 #include "google/cloud/spanner/database_admin_connection.h"
 #include "google/cloud/spanner/internal/defaults.h"
 #include "google/cloud/spanner/options.h"

diff --git a/google/cloud/spanner/database_admin_connection.h b/google/cloud/spanner/database_admin_connection.h
@@ -97,7 +97,8 @@ using ListBackupsRange = ::google::cloud::internal::PaginationRange<
  * To create a concrete instance that connects you to a real Cloud Spanner
  * instance administration service, see `MakeDatabaseAdminConnection()`.
  */
-class DatabaseAdminConnection {
+class GOOGLE_CLOUD_CPP_SPANNER_ADMIN_API_DEPRECATED("DatabaseAdminConnection")
+    DatabaseAdminConnection {
  public:
   virtual ~DatabaseAdminConnection() = 0;
 
@@ -341,6 +342,7 @@ class DatabaseAdminConnection {
  * @param opts (optional) configure the `DatabaseAdminConnection` created by
  *     this function.
  */
+GOOGLE_CLOUD_CPP_SPANNER_ADMIN_API_DEPRECATED("MakeDatabaseAdminConnection()")
 std::shared_ptr<spanner::DatabaseAdminConnection> MakeDatabaseAdminConnection(
     Options opts = {});
 
@@ -359,6 +361,7 @@ std::shared_ptr<spanner::DatabaseAdminConnection> MakeDatabaseAdminConnection(
  * @param options configure the `DatabaseAdminConnection` created by this
  *     function.
  */
+GOOGLE_CLOUD_CPP_SPANNER_ADMIN_API_DEPRECATED("MakeDatabaseAdminConnection()")
 std::shared_ptr<DatabaseAdminConnection> MakeDatabaseAdminConnection(
     ConnectionOptions const& options);
 
@@ -384,6 +387,7 @@ std::shared_ptr<DatabaseAdminConnection> MakeDatabaseAdminConnection(
  * @par Example
  * @snippet samples.cc custom-database-admin-policies
  */
+GOOGLE_CLOUD_CPP_SPANNER_ADMIN_API_DEPRECATED("MakeDatabaseAdminConnection()")
 std::shared_ptr<DatabaseAdminConnection> MakeDatabaseAdminConnection(
     ConnectionOptions const& options, std::unique_ptr<RetryPolicy> retry_policy,
     std::unique_ptr<BackoffPolicy> backoff_policy,

diff --git a/google/cloud/spanner/database_admin_connection_test.cc b/google/cloud/spanner/database_admin_connection_test.cc
@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// TODO(#7356): Remove this file after the deprecation period expires
+#include "google/cloud/internal/disable_deprecation_warnings.inc"
 #include "google/cloud/spanner/database_admin_connection.h"
 #include "google/cloud/spanner/internal/defaults.h"
 #include "google/cloud/spanner/options.h"

diff --git a/google/cloud/spanner/instance_admin_client.cc b/google/cloud/spanner/instance_admin_client.cc
@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// TODO(#7356): Remove this file after the deprecation period expires
+#include "google/cloud/internal/disable_deprecation_warnings.inc"
 #include "google/cloud/spanner/instance_admin_client.h"
 
 namespace google {

diff --git a/google/cloud/spanner/instance_admin_client.h b/google/cloud/spanner/instance_admin_client.h
@@ -61,7 +61,8 @@ inline namespace SPANNER_CLIENT_NS {
  * [spanner-doc-link]:
  * https://cloud.google.com/spanner/docs/api-libraries-overview
  */
-class InstanceAdminClient {
+class GOOGLE_CLOUD_CPP_SPANNER_ADMIN_API_DEPRECATED("InstanceAdminClient")
+    InstanceAdminClient {
  public:
   explicit InstanceAdminClient(std::shared_ptr<InstanceAdminConnection> conn)
       : conn_(std::move(conn)) {}

diff --git a/google/cloud/spanner/instance_admin_client_test.cc b/google/cloud/spanner/instance_admin_client_test.cc
@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// TODO(#7356): Remove this file after the deprecation period expires
+#include "google/cloud/internal/disable_deprecation_warnings.inc"
 #include "google/cloud/spanner/instance_admin_client.h"
 #include "google/cloud/spanner/mocks/mock_instance_admin_connection.h"
 #include "google/cloud/testing_util/status_matchers.h"

diff --git a/google/cloud/spanner/instance_admin_connection.cc b/google/cloud/spanner/instance_admin_connection.cc
@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// TODO(#7356): Remove this file after the deprecation period expires
+#include "google/cloud/internal/disable_deprecation_warnings.inc"
 #include "google/cloud/spanner/instance_admin_connection.h"
 #include "google/cloud/spanner/instance.h"
 #include "google/cloud/spanner/internal/defaults.h"

diff --git a/google/cloud/spanner/instance_admin_connection.h b/google/cloud/spanner/instance_admin_connection.h
@@ -67,7 +67,8 @@ using ListInstanceConfigsRange = ::google::cloud::internal::PaginationRange<
  * To create a concrete instance that connects you to a real Cloud Spanner
  * instance administration service, see `MakeInstanceAdminConnection()`.
  */
-class InstanceAdminConnection {
+class GOOGLE_CLOUD_CPP_SPANNER_ADMIN_API_DEPRECATED("InstanceAdminConnection")
+    InstanceAdminConnection {
  public:
   virtual ~InstanceAdminConnection() = 0;
 
@@ -219,6 +220,7 @@ class InstanceAdminConnection {
  * @param opts (optional) configure the `InstanceAdminConnection` created by
  *     this function.
  */
+GOOGLE_CLOUD_CPP_SPANNER_ADMIN_API_DEPRECATED("MakeInstanceAdminConnection()")
 std::shared_ptr<spanner::InstanceAdminConnection> MakeInstanceAdminConnection(
     Options opts = {});
 
@@ -237,6 +239,7 @@ std::shared_ptr<spanner::InstanceAdminConnection> MakeInstanceAdminConnection(
  * @param options configure the `InstanceAdminConnection` created by this
  *     function.
  */
+GOOGLE_CLOUD_CPP_SPANNER_ADMIN_API_DEPRECATED("MakeInstanceAdminConnection()")
 std::shared_ptr<InstanceAdminConnection> MakeInstanceAdminConnection(
     ConnectionOptions const& options);
 
@@ -262,6 +265,7 @@ std::shared_ptr<InstanceAdminConnection> MakeInstanceAdminConnection(
  * @par Example
  * @snippet samples.cc custom-instance-admin-policies
  */
+GOOGLE_CLOUD_CPP_SPANNER_ADMIN_API_DEPRECATED("MakeInstanceAdminConnection()")
 std::shared_ptr<InstanceAdminConnection> MakeInstanceAdminConnection(
     ConnectionOptions const& options, std::unique_ptr<RetryPolicy> retry_policy,
     std::unique_ptr<BackoffPolicy> backoff_policy,

diff --git a/google/cloud/spanner/instance_admin_connection_test.cc b/google/cloud/spanner/instance_admin_connection_test.cc
@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// TODO(#7356): Remove this file after the deprecation period expires
+#include "google/cloud/internal/disable_deprecation_warnings.inc"
 #include "google/cloud/spanner/instance_admin_connection.h"
 #include "google/cloud/spanner/create_instance_request_builder.h"
 #include "google/cloud/spanner/internal/defaults.h"

diff --git a/google/cloud/spanner/integration_tests/backup_integration_test.cc b/google/cloud/spanner/integration_tests/backup_integration_test.cc
@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// TODO(#7356): Remove this file after the deprecation period expires
+#include "google/cloud/internal/disable_deprecation_warnings.inc"
 #include "google/cloud/spanner/client.h"
 #include "google/cloud/spanner/database_admin_client.h"
 #include "google/cloud/spanner/instance_admin_client.h"

diff --git a/google/cloud/spanner/integration_tests/client_integration_test.cc b/google/cloud/spanner/integration_tests/client_integration_test.cc
@@ -14,7 +14,6 @@
 
 #include "google/cloud/spanner/client.h"
 #include "google/cloud/spanner/database.h"
-#include "google/cloud/spanner/database_admin_client.h"
 #include "google/cloud/spanner/mutations.h"
 #include "google/cloud/spanner/testing/database_integration_test.h"
 #include "google/cloud/internal/getenv.h"

diff --git a/google/cloud/spanner/integration_tests/data_types_integration_test.cc b/google/cloud/spanner/integration_tests/data_types_integration_test.cc
@@ -14,7 +14,6 @@
 
 #include "google/cloud/spanner/client.h"
 #include "google/cloud/spanner/database.h"
-#include "google/cloud/spanner/database_admin_client.h"
 #include "google/cloud/spanner/mutations.h"
 #include "google/cloud/spanner/testing/database_integration_test.h"
 #include "google/cloud/spanner/timestamp.h"

diff --git a/google/cloud/spanner/integration_tests/database_admin_integration_test.cc b/google/cloud/spanner/integration_tests/database_admin_integration_test.cc
@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// TODO(#7356): Remove this file after the deprecation period expires
+#include "google/cloud/internal/disable_deprecation_warnings.inc"
 #include "google/cloud/spanner/database.h"
 #include "google/cloud/spanner/database_admin_client.h"
 #include "google/cloud/spanner/testing/instance_location.h"

diff --git a/google/cloud/spanner/integration_tests/instance_admin_integration_test.cc b/google/cloud/spanner/integration_tests/instance_admin_integration_test.cc
@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// TODO(#7356): Remove this file after the deprecation period expires
+#include "google/cloud/internal/disable_deprecation_warnings.inc"
 #include "google/cloud/spanner/create_instance_request_builder.h"
 #include "google/cloud/spanner/instance_admin_client.h"
 #include "google/cloud/spanner/testing/cleanup_stale_instances.h"

diff --git a/google/cloud/spanner/version.h b/google/cloud/spanner/version.h
@@ -16,9 +16,17 @@
 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_VERSION_H
 
 #include "google/cloud/spanner/version_info.h"
+#include "google/cloud/internal/attributes.h"
 #include "google/cloud/version.h"
 #include <string>
 
+#define GOOGLE_CLOUD_CPP_SPANNER_ADMIN_API_DEPRECATED(name)                 \
+  GOOGLE_CLOUD_CPP_DEPRECATED(                                              \
+      "google::cloud::spanner::" name                                       \
+      " is deprecated, and will be removed on or shortly after 2022-10-01." \
+      " Please use google::cloud::spanner_admin::" name                     \
+      " instead. See GitHub issue #7356 for more information.")
+
 #define SPANNER_CLIENT_NS GOOGLE_CLOUD_CPP_NS
 
 namespace google {