feat(docs): add devsite-help and snippets for Retries, Update Masks, and OCC for IAM #15308

bshaffer · 2025-12-08T21:41:15Z

I followed the examples of other pages in docs/devsite-help, but it's quite possible I'm missing a critical aspect. I also am not sure how these will be tested.

I ran all samples locally to verify they worked but please take a look and review

Docs content
Sample code
How I've connected things up

gemini-code-assist · 2025-12-08T21:41:33Z

Summary of Changes

Hello @bshaffer, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the documentation for Google Cloud .NET client libraries by introducing three new guides focused on advanced usage patterns. These guides cover Optimistic Concurrency Control for IAM policies, flexible retry and timeout configurations, and efficient partial resource updates using update masks. Each guide is complemented by practical C# code snippets, providing developers with clear instructions and examples to implement these critical features effectively.

Highlights

New Documentation Pages: Added comprehensive guides for Optimistic Concurrency Control (OCC) for IAM, configuring Retries and Timeouts, and utilizing Update Masks.
C# Code Snippets: Introduced corresponding C# code examples to illustrate the practical application of OCC, retry mechanisms, and update masks within Google Cloud .NET client libraries.
Table of Contents Integration: Updated the docs/devsite-help/toc.yml file to ensure the new documentation pages are discoverable and properly linked within the documentation structure.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

github-actions · 2025-12-08T21:42:32Z

Pull request diff results
No APIs have changed in this PR. Exiting diff.

gemini-code-assist

Code Review

This pull request adds valuable documentation and examples for Retries, Update Masks, and Optimistic Concurrency Control for IAM. The documentation content is clear and well-structured. However, all the new C# code snippets contain several compilation errors that need to be addressed. These include incorrect async method signatures, use of an undefined _fixture variable, a missing semicolon, and unused using directives. I've left specific comments with suggestions to fix these issues. Once these are resolved, the snippets will be great examples for users.

tools/Google.Cloud.Docs.Snippets/OccForIamSnippets.cs

tools/Google.Cloud.Docs.Snippets/RetriesSnippets.cs

tools/Google.Cloud.Docs.Snippets/UpdateMaskSnippets.cs

tools/Google.Cloud.Docs.Snippets/OccForIamSnippets.cs

tools/Google.Cloud.Docs.Snippets/RetriesSnippets.cs

tools/Google.Cloud.Docs.Snippets/UpdateMaskSnippets.cs

… OCC for IAM

github-actions · 2025-12-10T22:14:53Z

Pull request diff results
No APIs have changed in this PR. Exiting diff.

amanda-tarafa

Let me know how I can help.

amanda-tarafa · 2025-12-15T23:27:39Z

tools/Google.Cloud.Docs.Snippets/UpdateMaskSnippets.cs

+using Google.Protobuf.WellKnownTypes;
+using Grpc.Core;
+
+namespace Google.Cloud.Tools.Snippets


File scoped namespace (no curly brackets, see tools/Google.Cloud.Docs.Snippets/LongRunningOperationsSnippets.cs) for new files, here and in the others.

amanda-tarafa · 2025-12-15T23:28:14Z

tools/Google.Cloud.Docs.Snippets/UpdateMaskSnippets.cs

+{
+    public class UpdateMaskSnippets
+    {
+        public async Task UpdateMasks()


This won't run as a test. See https://github.com/googleapis/google-cloud-dotnet/blob/main/tools/Google.Cloud.Docs.Snippets/CallSettingsSnippets.cs for an example.

amanda-tarafa · 2025-12-15T23:28:39Z

tools/Google.Cloud.Docs.Snippets/UpdateMaskSnippets.cs

+            string projectId = "your-project-id";
+            string secretId = "test-secret";


So that this is run, these need to come from the fixture.

amanda-tarafa · 2025-12-15T23:32:57Z

tools/Google.Cloud.Docs.Snippets/UpdateMaskSnippets.cs

+            // Required using directives:
+            // using Google.Cloud.SecretManager.V1;
+            // using Google.Protobuf.WellKnownTypes;
+            // using Grpc.Core;


We don't have these in the other product neutral samples. Let's keep the consistency.

tools/Google.Cloud.Docs.Snippets/UpdateMaskSnippets.cs

amanda-tarafa · 2025-12-16T00:13:04Z

docs/devsite-help/toc.yml

+  - name: Retries
+    href: retries.md


We have these in CallSettings already.

amanda-tarafa · 2025-12-16T00:14:13Z

docs/devsite-help/retries.md

@@ -0,0 +1,32 @@
+# Configuring Retries and Timeouts


Look at the one in call-settings.md and maybe modify it if there's something missing from there, plus, add the sample code that we already have?

amanda-tarafa · 2025-12-16T00:14:35Z

docs/devsite-help/occ-for-iam.md

@@ -0,0 +1,26 @@
+# Optimistic Concurrency Control (OCC) Loop for IAM


Suggested change

# Optimistic Concurrency Control (OCC) Loop for IAM

# Optimistic Concurrency Control (OCC) for IAM

And also, why does this need to be IAM specific? I think we can use IAM for examples but the same principles apply to many APIs that have Etags for their resources? (I should have left this commenton the initial content review, but it only occured to me now).

amanda-tarafa · 2025-12-16T00:17:37Z

docs/devsite-help/occ-for-iam.md

+
+Optimistic Concurrency Control (OCC) is a strategy used to manage shared resources and prevent "lost updates" or race conditions when multiple users or processes attempt to modify the same resource simultaneously.
+
+In the context of Google Cloud .NET libraries, IAM Policy objects contain an `Etag` property. When calling `SetIamPolicy`, the client library includes this `Etag`. If the server detects that the `Etag` provided does not match the current version on the server, it throws an RPC exception with the status `Aborted` or `FailedPrecondition`.


Is there any info about the difference between Aborted or FailedPrecondition?

amanda-tarafa · 2025-12-16T00:19:39Z

docs/devsite-help/occ-for-iam.md

+
+In the context of Google Cloud .NET libraries, IAM Policy objects contain an `Etag` property. When calling `SetIamPolicy`, the client library includes this `Etag`. If the server detects that the `Etag` provided does not match the current version on the server, it throws an RPC exception with the status `Aborted` or `FailedPrecondition`.
+
+## Implementing the OCC Loop


Same comment as before, I don't think we need to show or describe an actual retry loop. For instance, for someone building a UI to allow users to modify an OCCed resource, they might not want to retry, they might want to notify the user and let the user retry (by clicking the button again) etc.

bshaffer requested a review from a team as a code owner December 8, 2025 21:41

gemini-code-assist bot reviewed Dec 8, 2025

View reviewed changes

feat(docs): add devsite-help and tests for Retries, Update Masks, and…

cd55d59

… OCC for IAM

bshaffer force-pushed the add-client-help-docs branch from ad64163 to cd55d59 Compare December 10, 2025 22:13

googleapis deleted a comment from github-actions bot Dec 10, 2025

update copyright

8621a55

amanda-tarafa requested changes Dec 16, 2025

View reviewed changes

googleapis deleted a comment from github-actions bot Dec 16, 2025

		string projectId = "your-project-id";
		string secretId = "test-secret";

		@@ -0,0 +1,26 @@
		# Optimistic Concurrency Control (OCC) Loop for IAM

	# Optimistic Concurrency Control (OCC) Loop for IAM
	# Optimistic Concurrency Control (OCC) for IAM


		Optimistic Concurrency Control (OCC) is a strategy used to manage shared resources and prevent "lost updates" or race conditions when multiple users or processes attempt to modify the same resource simultaneously.

		In the context of Google Cloud .NET libraries, IAM Policy objects contain an `Etag` property. When calling `SetIamPolicy`, the client library includes this `Etag`. If the server detects that the `Etag` provided does not match the current version on the server, it throws an RPC exception with the status `Aborted` or `FailedPrecondition`.


		In the context of Google Cloud .NET libraries, IAM Policy objects contain an `Etag` property. When calling `SetIamPolicy`, the client library includes this `Etag`. If the server detects that the `Etag` provided does not match the current version on the server, it throws an RPC exception with the status `Aborted` or `FailedPrecondition`.

		## Implementing the OCC Loop

feat(docs): add devsite-help and snippets for Retries, Update Masks, and OCC for IAM #15308

Are you sure you want to change the base?

feat(docs): add devsite-help and snippets for Retries, Update Masks, and OCC for IAM #15308

Uh oh!

Conversation

bshaffer commented Dec 8, 2025

Uh oh!

gemini-code-assist bot commented Dec 8, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

github-actions bot commented Dec 8, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Dec 10, 2025

Uh oh!

amanda-tarafa left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants