# Write Devrel Sample

> Use this skill when asked to write a DevRel sample.

- Skill: `googleapis/write-devrel-sample-2` (Agent Skill)
- Install (CLI): `npx get-skill add googleapis/write-devrel-sample-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/googleapis/write-devrel-sample-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: googleapis (https://skillmd.com/u/googleapis)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/googleapis/write-devrel-sample-2

---


# Task

You need to write a sample using a Swift client library.

You will be given a DevRel region tag, or a GitHub issue that requests adding
the region tag. A region tag is a way for Google Cloud to associate the sample
code with its documentation.

## Identify the sample

First, identify which service this is for. This is almost always the first word
in the snake case of the region. For example, if the region is
`storage_list_buckets`, the service will be `storage`.

Next, identify where the examples for this service live in the codebase. For
storage this will be the `Sources/StorageSamples` directory. We anticipate
that future clients will follow similar patterns, e.g. Pub/Sub samples will be
in `Sources/PubSubSamples`.

If this directory does not exist, stop and ask your human for help.

## Identify the sample package

Next identify the name of the target for the examples. Look at the top-level
`Package.swift` file. By convention this is the same name as the directory
containing the samples.

### Local dependencies (`swift package edit`)

Packages in this repository declare dependencies on published remote GitHub
URLs by default. When building samples against local changes or unreleased
features in `pkgs/*` or `generated/*` (such as `swift-google-gax`,
`swift-google-auth`, or `swift-google-wkt`), you must put those dependencies
into edit mode pointing to local checkouts:

```shell
REPO_ROOT="$(git rev-parse --show-toplevel)"
swift package edit --path "${REPO_ROOT}/pkgs/swift-google-gax" swift-google-gax
swift package edit --path "${REPO_ROOT}/pkgs/swift-google-auth" swift-google-auth
swift package edit --path "${REPO_ROOT}/pkgs/swift-google-wkt" swift-google-wkt
```

Alternatively, use the helper function from `ci/package-dependencies.sh`:

```shell
source ci/package-dependencies.sh
edit_package_dependencies .
```

Always remember to restore dependencies with `swift package unedit` or
`restore_package_dependencies .` before creating a pull request.

### Build the samples target

Validate the code compiles using:

```shell
swift build --target <SamplesTarget>
```

### Identify and run the sample test driver

Identify the name of the test for the examples. Look at the top-level
`Package.swift` and find tests that depend on this target. By convention the
test is called `<SamplesTarget>Driver`.

The sample drivers (such as `StorageSamplesDriver`) typically require specific
environment variables to be enabled, including `GOOGLE_CLOUD_PROJECT` and
`GOOGLE_CLOUD_SWIFT_TEST_ENABLE_FLAKES=true`. Without
`GOOGLE_CLOUD_SWIFT_TEST_ENABLE_FLAKES=true`, the tests are silently skipped.
Read `ci/gcb/scripts/integration-tests.sh` for other relevant environment
variables:

```shell
PROJECT_ID=$(gcloud config get project)
export GOOGLE_CLOUD_PROJECT="${PROJECT_ID}"
export GOOGLE_CLOUD_SWIFT_TEST_ENABLE_FLAKES=true
export GOOGLE_CLOUD_SWIFT_TEST_SERVICE_ACCOUNT="swift-sdk-test@${PROJECT_ID}.iam.gserviceaccount.com"
export GOOGLE_CLOUD_SWIFT_TEST_STORAGE_KMS_KEY_RING=us-central1
```

Run the test driver using:

```shell
GOOGLE_CLOUD_PROJECT=${PROJECT_ID} GOOGLE_CLOUD_SWIFT_TEST_ENABLE_FLAKES=true \
    swift test --filter <SamplesTargetDriver>
```

You can also filter to a specific test method to save time (e.g.
`--filter runObjectSamples`):

```shell
GOOGLE_CLOUD_PROJECT=${PROJECT_ID} GOOGLE_CLOUD_SWIFT_TEST_ENABLE_FLAKES=true \
    swift test --filter <testMethod>
```

When the tests are enabled and pass, you are done with this step. You can move on
to the next one.


## Research prior art

### Look for the same sample written in other languages.

Do a CodeSearch for the given sample region. e.g. search for
`"[START storage_list_buckets]"`. This will show how other client libraries (in
languages other than Swift) write the code. Read up to 5 of these examples to
understand what the sample is doing.

Alternatively, clone the `https://github.com/googleapis/google-cloud-rust`
repository and find the sample there. The Swift SDK uses some of the same
conventions as the Rust SDK, and the Rust SDK already has most samples.

Aside: If you are a human, you could do a Google search and try to find the
cloud.google.com docs associated with this region. For example
https://docs.cloud.google.com/storage/docs/listing-buckets is associated with
`storage_list_buckets`.

Note that other client libraries have different surfaces. We will need to adapt
the logic for the exact API exposed by Swift.

### Look for existing Swift samples for the same service.

Search the local codebase (e.g., `grep -r "key_term" Sources/<SamplesTarget>`) for key
terms from the region tag to identify the relevant Swift structs, methods, and
fields.

Look at the structure under `Sources/<SamplesTarget>`. Read every file to
discover common patterns for the samples.

Next read everything under `Tests/<SamplesTargetDriver>` to see how individual
samples are invoked.

### Identify where this sample should go.

Figure out where to create a new `<sample>.swift` file. Typically, we use the
region tag for the filename, but strip any prefixes that are encoded in the
directory structure. For example, the `storage_list_buckets` sample is located
under `Sources/StorageSamples/Buckets/ListBuckets.swift`

### Identify the most similar sample to the one you are writing

Identify which existing sample is most similar to the one you are about to
write. It is useful to identify:

- which client is used?
- which RPC is used?
- which fields in the RPC are important?

Examples:

- If the sample is to set a field in an RPC, find a sample that makes that same
  RPC.
- If the sample is to make an RPC we haven't seen, find a sample that makes a
  different RPC, with the same client.

### Look for Swift samples in the documentation.

Look at examples in the documentation (i.e. in `generated/<service>/Snippets/...` or `pkgs/<service>/Snippets/...`) for any
interfaces you will use in the sample. If we find examples in the documentation,
the sample you write should resemble it.

## Write the sample

### Initial set up

First create a file for this new sample. It is easiest to copy the sample that
is most similar to this one and make edits. Don't make edits just yet, though.

The sample should always include a copyright, and use a DevRel snippet region
tag (the things that looks like `// [START <snippet_region>]` and
`// [END <snippet_region>]`)

### Verify the new sample is run.

Add a `fatalError("TODO : making sure the test is run")` inside the sample
function, and then execute the samples as before.

```shell
GOOGLE_CLOUD_PROJECT=${PROJECT_ID} GOOGLE_CLOUD_SWIFT_TEST_ENABLE_FLAKES=true \
    swift test --filter <TargetSample>Driver
```

We should see this fail. If it does not fail, then we are not running our
sample. Make sure the new sample is executed by the test driver.

If it does fail, you can remove the `fatalError` and move on.

### Iterate

Next, edit the interior of the sample to fit the given DevRel snippet region.
This is where it is useful to remember what other languages did.

### Use named parameters in nested `.with` closures

When constructing or modifying requests and proto models using
`.with { ... }`, the outermost closure may use anonymous `$0`, but **nested**
`.with` closures must use explicit named parameter contexts (e.g.,
`{ options in ... }`, `{ bucket in ... }`, `{ iamConfig in ... }`).

Nesting multiple `$0` closures shadows the outer scope and impairs readability.

```swift
// AVOID: nested closures reusing anonymous $0
request: .init().with {
  $0.resource = "projects/_/buckets/\(bucketId)"
  $0.options = .init().with {
    $0.requestedPolicyVersion = 3
  }
}

// PREFER: named parameter for inner closures
request: .init().with {
  $0.resource = "projects/_/buckets/\(bucketId)"
  $0.options = .init().with { options in
    options.requestedPolicyVersion = 3
  }
}
```

For multi-level nesting (such as in `CreateBucketClassLocation.swift` or
`CreateBucketWithEncryptionEnforcement.swift`), chain named contexts
descriptively at each level:

```swift
$0.bucket = .init().with { bucket in
  bucket.project = "projects/\(projectId)"
  bucket.iamConfig = .init().with { iamConfig in
    iamConfig.uniformBucketLevelAccess = .init().with { ubla in
      ubla.enabled = true
    }
  }
}
```

When you are done, test the code:

```shell
GOOGLE_CLOUD_PROJECT=${PROJECT_ID} GOOGLE_CLOUD_SWIFT_TEST_ENABLE_FLAKES=true \
    swift test --filter <TargetSample>Driver
```

If this doesn't pass, keep making edits until it works. If you fail too many
times in a row, ask for help.

When this passes, clean up the code.

- Make it concise.
- Restore any edited dependencies back to remote Git URLs:
  ```shell
  source ci/package-dependencies.sh
  restore_package_dependencies .
  ```
  Or individually:
  ```shell
  swift package unedit --force swift-google-gax
  swift package unedit --force swift-google-auth
  swift package unedit --force swift-google-wkt
  git restore Package.resolved
  ```
- Run `ci/format.sh` (or `swift-format format -i -r ...`).
- Verify linting passes with `swift-format lint -s ...` (or `./ci/lint.sh pr`).
- Look over other things from `GEMINI.md`.

If you make any changes, test the code again.

## Report success!

Stop and report success to the human! What changes did you make to the repo?

Also, suggest any updates to this `SKILL.md` in an `EDITS.diff` that will
improve the process for next time. If the process went well, there is no need to
make any suggestions.

