From 39bd9dfa93da9c82f7689553be637d42b58461fd Mon Sep 17 00:00:00 2001 From: Scott Hart Date: Thu, 27 Aug 2026 15:26:30 -0400 Subject: [PATCH 1/3] doc: add generate-library skill --- .agents/skills/generate-library/SKILL.md | 213 +++++++++++++++++++++++ 1 file changed, 213 insertions(+) create mode 100644 .agents/skills/generate-library/SKILL.md diff --git a/.agents/skills/generate-library/SKILL.md b/.agents/skills/generate-library/SKILL.md new file mode 100644 index 0000000000000..c8b56577e15e1 --- /dev/null +++ b/.agents/skills/generate-library/SKILL.md @@ -0,0 +1,213 @@ +--- +name: generate-library +description: Generates a new C++ client library for google-cloud-cpp from a Buganizer library generation request. Use when asked to generate, scaffold, or onboard a new Google Cloud service or library, or when given a Buganizer issue ID (e.g., b/123456789). +--- + +# Generate New Library from Buganizer Request + +This skill guides the end-to-end process of generating and validating a new C++ +client library in `google-cloud-cpp` from a Buganizer generation request +(b/...). + +> **Reference Documentation**: +> +> - [How-to Guide: Adding generated libraries](doc/contributor/howto-guide-adding-generated-libraries.md) +> - [How-to Guide: Updating googleapis SHA](doc/contributor/howto-guide-update-googleapis-sha.md) +> (if the proto dependency is not yet available at the pinned googleapis SHA) + +______________________________________________________________________ + +## 1. Parse the Buganizer Request + +Fetch the issue details using the Buganizer CLI: + +```bash +/google/bin/releases/issues-cli/issues render +``` + +Extract the following information: + +1. **Service YAML / Proto Path**: e.g., + `google/cloud/biglake/hive/v1/biglake_v1.yaml` +1. **`PiperOrigin-RevId`**: Required in the commit description (e.g., + `PiperOrigin-RevId: 966248502`). +1. **Service Details**: + - Library name (e.g., `biglake` from `api_short_name` in the YAML). + - Product path (e.g., `google/cloud/biglake/hive/v1`). + - Service Proto path (e.g., + `google/cloud/biglake/hive/v1/hive_metastore.proto`). + - Launch stage (`GA` vs `EXPERIMENTAL`). + +______________________________________________________________________ + +## 2. Inspect Googleapis Rules and Service Configuration + +1. **Find the Bazel Output Base**: + + ```bash + bazel_output_base="$(bazelisk info output_base)" + ``` + +1. **Query the C++ gRPC Rule**: + + ```bash + bazelisk query --noshow_progress --noshow_loading_progress \ + "kind(cc_library, @googleapis///...)" + ``` + + Note the exact target name (e.g. + `@googleapis//google/cloud/biglake/hive/v1:hive_cc_grpc`). + +1. **Determine Retryable Status Codes**: Inspect + `/external/googleapis+//*_grpc_service_config.json`. + Map status codes to C++ enum values: + + - `UNAVAILABLE` -> `"kUnavailable"` + - `DEADLINE_EXCEEDED` -> `"kDeadlineExceeded"` + - `RESOURCE_EXHAUSTED` -> `"kResourceExhausted"` + - `UNAUTHENTICATED` -> `"kUnauthenticated"` + +______________________________________________________________________ + +## 3. Step-by-Step Implementation + +### Step 3.1: Update Scripts and Generator Config + +1. **Edit + [external/googleapis/update_libraries.sh](external/googleapis/update_libraries.sh)**: + Add the library mapping in alphabetical order to `LIBRARIES`: + + ```bash + [""]="@googleapis//:_cc_grpc" + ``` + +1. **Edit + [generator/generator_config.textproto](generator/generator_config.textproto)**: + Add the service configuration block in alphabetical order: + + ```textproto + # + service { + service_proto_path: "/.proto" + product_path: "" + initial_copyright_year: "" + retryable_status_codes: ["kUnavailable", ...] + } + ``` + +### Step 3.2: Check Out Branch & Commit Initial Config + +```bash +git checkout -b feat--generate-library +git commit -m "feat(): generate library" external/ generator/ +``` + +### Step 3.3: Generate Proto Lists & Dependencies + +```bash +external/googleapis/update_libraries.sh "" +``` + +### Step 3.4: Run Scaffold Generator + +```bash +bazelisk run \ + //generator:google-cloud-cpp-codegen -- \ + --protobuf_proto_path="${bazel_output_base}/external/protobuf+/src" \ + --googleapis_proto_path="${bazel_output_base}/external/googleapis+" \ + --discovery_proto_path="${PWD}/protos" \ + --output_path="${PWD}" \ + --config_file="${PWD}/generator/generator_config.textproto" \ + --scaffold_templates_path="${PWD}/generator/templates/" \ + --scaffold="google/cloud//" +``` + +_(Add `--experimental_scaffold` if the library launch stage is not GA)._ + +### Step 3.5: Fix Build Dependencies + +Verify `google/cloud//BUILD.bazel`: Ensure `googleapis_deps` uses the +exact gRPC target from Step 2 (e.g., `:hive_cc_grpc` instead of default +`:_cc_grpc`). + +### Step 3.6: Update Root Feature Lists + +1. **[cmake/GoogleCloudCppFeatures.cmake](cmake/GoogleCloudCppFeatures.cmake)**: + Add `""` in alphabetical order to `GOOGLE_CLOUD_CPP_GA_LIBRARIES` + (or `GOOGLE_CLOUD_CPP_EXPERIMENTAL_LIBRARIES`). +1. **[libraries.bzl](libraries.bzl)**: Add `""` in alphabetical order + to `GOOGLE_CLOUD_CPP_GA_LIBRARIES` (or + `GOOGLE_CLOUD_CPP_EXPERIMENTAL_LIBRARIES`). + +### Step 3.7: Implement Quickstart + +1. **`google/cloud//quickstart/quickstart.cc`**: + - Replace placeholder `#include` with the primary client header. + - Call a simple top-level list/get RPC (e.g., `ListCatalogs` or + `ListResources`). +1. **`google/cloud//CMakeLists.txt`**: + - Update test arguments in `add_test` for `biglake_quickstart` (e.g. + `GOOGLE_CLOUD_PROJECT`). +1. **`google/cloud//quickstart/README.md`**: + - Replace placeholder `[...]` command-line arguments. + +### Step 3.8: Update Documentation & Changelog + +1. **[CHANGELOG.md](CHANGELOG.md)**: Add the library under `New Libraries` in + the upcoming release section. +1. Ensure `google/cloud///.repo-metadata.json` exists + and is tracked. + +______________________________________________________________________ + +## 4. Format & Validate + +1. **Stage all files and run checkers**: + + ```bash + git add external ci cmake libraries.bzl CHANGELOG.md README.md "google/cloud/" + ci/cloudbuild/build.sh -t checkers-pr + ``` + + _(Re-run if formatters or documentation scripts made changes until checkers + pass cleanly with exit code 0)._ + +1. **Verify Bazel Build**: + + ```bash + bazelisk build //google/cloud//... + ``` + +1. **Verify Full CMake Installation & Quickstart**: + + ```bash + ci/cloudbuild/build.sh -t cmake-install-pr + ``` + +1. **Verify Full Generator Pipeline**: + + ```bash + ci/cloudbuild/build.sh -t generate-libraries-pr + ``` + +1. **Create and Verify API Baseline (GA libraries only)**: + + ```bash + env GOOGLE_CLOUD_CPP_CHECK_API= ci/cloudbuild/build.sh -t check-api-pr + git add ci/abi-dumps + env GOOGLE_CLOUD_CPP_CHECK_API= ci/cloudbuild/build.sh -t check-api-pr + ``` + +______________________________________________________________________ + +## 5. Commit Changes + +Commit all files with the `PiperOrigin-RevId` extracted from the Buganizer +request: + +```bash +git add -A +git commit -m "feat(): add C++ client library + +PiperOrigin-RevId: " +``` From d7ee2df5bfbeb2b11371fe21b731af03a35aa089 Mon Sep 17 00:00:00 2001 From: Scott Hart Date: Thu, 27 Aug 2026 16:09:41 -0400 Subject: [PATCH 2/3] Update .agents/skills/generate-library/SKILL.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- .agents/skills/generate-library/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/generate-library/SKILL.md b/.agents/skills/generate-library/SKILL.md index c8b56577e15e1..f8c5569cae94e 100644 --- a/.agents/skills/generate-library/SKILL.md +++ b/.agents/skills/generate-library/SKILL.md @@ -146,7 +146,7 @@ exact gRPC target from Step 2 (e.g., `:hive_cc_grpc` instead of default - Call a simple top-level list/get RPC (e.g., `ListCatalogs` or `ListResources`). 1. **`google/cloud//CMakeLists.txt`**: - - Update test arguments in `add_test` for `biglake_quickstart` (e.g. + - Update test arguments in add_test for _quickstart (e.g. `GOOGLE_CLOUD_PROJECT`). 1. **`google/cloud//quickstart/README.md`**: - Replace placeholder `[...]` command-line arguments. From e721aefae99fd5d95fa517ab3229d4c54c92f3a1 Mon Sep 17 00:00:00 2001 From: Scott Hart Date: Thu, 27 Aug 2026 16:56:32 -0400 Subject: [PATCH 3/3] formatting --- .agents/skills/generate-library/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/generate-library/SKILL.md b/.agents/skills/generate-library/SKILL.md index f8c5569cae94e..e448ac188e0f2 100644 --- a/.agents/skills/generate-library/SKILL.md +++ b/.agents/skills/generate-library/SKILL.md @@ -146,7 +146,7 @@ exact gRPC target from Step 2 (e.g., `:hive_cc_grpc` instead of default - Call a simple top-level list/get RPC (e.g., `ListCatalogs` or `ListResources`). 1. **`google/cloud//CMakeLists.txt`**: - - Update test arguments in add_test for _quickstart (e.g. + - Update test arguments in add_test for \_quickstart (e.g. `GOOGLE_CLOUD_PROJECT`). 1. **`google/cloud//quickstart/README.md`**: - Replace placeholder `[...]` command-line arguments.