Evaluating sdk-internal Updates
Identify both compile-time and runtime breaks before fixing anything — fixing the first break found is not finishing. Steps 3-7 always cover the entire commit range before step 8 starts, no matter how obvious or urgent an early compile-time break looks.
Identify
Binding surface facts specific to this SDK: #[uniffi::export] / derive(uniffi::...) annotations are scattered across many crates, not just crates/bitwarden-uniffi; crates/bitwarden-ffi is unrelated ("do not use"). No .udl files. UniFFI emits one Kotlin package per crate (com.bitwarden.core, com.bitwarden.vault, com.bitwarden.crypto, etc.) — only the top-level Client/AuthClient/GeneratorClients actually live under com.bitwarden.sdk. Both app and authenticator depend on the SDK; neither is optional to search.
A hunk that only touches a macro invocation (e.g. state_bridge! { ... }) doesn't show the binding surface — the expansion lives in the macro's definition, often in a different crate (e.g. bitwarden-state-bridge-macro). #[uniffi::export(with_foreign)] marks a callback interface: a trait Kotlin must implement, where adding a field/method is never additive-safe for the implementor.
- Locate the local
bitwarden/sdk-internal clone (check sibling directories to this repo). If none exists, stop and tell the user it's a required prerequisite for this skill — do not clone it yourself.
gh pr diff <PR> -R bitwarden/android | grep bitwardenSdk → old/new bitwardenSdk string. Everything after the second - is the git ref — a commit SHA or a branch name (.dev SDK builds use both); resolve a branch name as origin/<branch> in the clone.- Attempt
./gradlew app:compileStandardDebugKotlin authenticator:compileDebugKotlin at the current checkout before crawling sdk-internal. A failure confirms a compile-time break directly, with a more precise location than any git search — note it and continue to steps 4-7 for the full commit range; do not fix it yet. A clean build only rules out compile-time breaks, not runtime ones.
git -C <sdk-internal-path> log --oneline OLD..NEW -G'uniffi::export|derive\(uniffi|#\[uniffi' -- '*.rs' → candidate binding-surface commits.- Classify per hunk, not per commit — a commit with one additive headline change can still have a second, unrelated breaking hunk. If a hunk only touches a macro invocation, read the macro's definition before classifying.
git -C <sdk-internal-path> show <sha> -- '*.rs'.
- For every distinct symbol/type touched (every hunk, not just the commit's headline change), grep the whole repo for the bare symbol name to find Android call sites — a fixed module list or a
com.bitwarden.sdk.<Symbol> import-prefix check both miss real consumers.
- Report: compile-time breaks, runtime breaks, safe/no-call-site — each with commit, symbol, and call sites. Cite sdk-internal commits and PRs as
bitwarden/sdk-internal#<NNN> or a full commit URL/SHA — never a bare #<NNN> copied from a commit subject line. A bare reference auto-links within whatever repo the report is posted to (e.g. bitwarden/android), tagging an unrelated issue or PR there.
Resolve
Resolve the findings from Step 7 by deciding on a fix (step 8), implementing and committing it directly (step 9), then verifying (step 10).
- Decide the fix for anything found, compile-time or runtime, whenever the correct behavior is clear and within scope. For a new required method, grep for the underlying concept, not the new method/type name (it won't exist yet) — no existing consumer means stub it: a
// no-op comment or a null/default return that satisfies the compiler, not a behavioral decision. Never TODO() — it throws at runtime, which is a crash, not a stub. A sibling's structure (naming, placement, style) is a template; its behavior (storage, defaulting, error handling, side effects) is not evidence for yours. If unsure, report it instead of guessing, along with anything needing a product decision.
- Implement every fix from step 8 directly: invoke
Skill(implementing-android-code) first if the fix isn't purely mechanical, then commit with Skill(bitwarden-delivery-tools:committing-changes).
- Verify with the same compile task used in step 3.
1---2name: evaluating-sdk-internal-updates3description: Evaluates a bitwarden/android "Update SDK to" PR against the sdk-internal commit range for compile-time and runtime breaking changes, maps affected symbols to Android call sites, and applies clear in-scope fixes. Use when reviewing an SDK bump PR, a bitwardenSdk version change, or triaging sdk-internal breaking changes.4---56# Evaluating sdk-internal Updates78**Identify both compile-time and runtime breaks before fixing anything — fixing the first break found is not finishing.** Steps 3-7 always cover the entire commit range before step 8 starts, no matter how obvious or urgent an early compile-time break looks.910## Identify1112Binding surface facts specific to this SDK: `#[uniffi::export]` / `derive(uniffi::...)` annotations are scattered across many crates, not just `crates/bitwarden-uniffi`; `crates/bitwarden-ffi` is unrelated ("do not use"). No `.udl` files. UniFFI emits one Kotlin package per crate (`com.bitwarden.core`, `com.bitwarden.vault`, `com.bitwarden.crypto`, etc.) — only the top-level `Client`/`AuthClient`/`GeneratorClients` actually live under `com.bitwarden.sdk`. Both `app` and `authenticator` depend on the SDK; neither is optional to search.1314A hunk that only touches a macro invocation (e.g. `state_bridge! { ... }`) doesn't show the binding surface — the expansion lives in the macro's definition, often in a different crate (e.g. `bitwarden-state-bridge-macro`). `#[uniffi::export(with_foreign)]` marks a callback interface: a trait Kotlin must implement, where adding a field/method is never additive-safe for the implementor.15161. Locate the local `bitwarden/sdk-internal` clone (check sibling directories to this repo). If none exists, stop and tell the user it's a required prerequisite for this skill — do not clone it yourself.172. `gh pr diff <PR> -R bitwarden/android | grep bitwardenSdk` → old/new `bitwardenSdk` string. Everything after the second `-` is the git ref — a commit SHA or a branch name (`.dev` SDK builds use both); resolve a branch name as `origin/<branch>` in the clone.183. Attempt `./gradlew app:compileStandardDebugKotlin authenticator:compileDebugKotlin` at the current checkout before crawling sdk-internal. A failure confirms a compile-time break directly, with a more precise location than any git search — note it and continue to steps 4-7 for the full commit range; do not fix it yet. A clean build only rules out compile-time breaks, not runtime ones.194. `git -C <sdk-internal-path> log --oneline OLD..NEW -G'uniffi::export|derive\(uniffi|#\[uniffi' -- '*.rs'` → candidate binding-surface commits.205. Classify per hunk, not per commit — a commit with one additive headline change can still have a second, unrelated breaking hunk. If a hunk only touches a macro invocation, read the macro's definition before classifying. `git -C <sdk-internal-path> show <sha> -- '*.rs'`.216. For every distinct symbol/type touched (every hunk, not just the commit's headline change), grep the whole repo for the bare symbol name to find Android call sites — a fixed module list or a `com.bitwarden.sdk.<Symbol>` import-prefix check both miss real consumers.227. Report: compile-time breaks, runtime breaks, safe/no-call-site — each with commit, symbol, and call sites. Cite sdk-internal commits and PRs as `bitwarden/sdk-internal#<NNN>` or a full commit URL/SHA — never a bare `#<NNN>` copied from a commit subject line. A bare reference auto-links within whatever repo the report is posted to (e.g. `bitwarden/android`), tagging an unrelated issue or PR there.2324## Resolve2526Resolve the findings from Step 7 by deciding on a fix (step 8), implementing and committing it directly (step 9), then verifying (step 10).27288. Decide the fix for anything found, compile-time or runtime, whenever the correct behavior is clear and within scope. For a new required method, grep for the underlying concept, not the new method/type name (it won't exist yet) — no existing consumer means stub it: a `// no-op` comment or a null/default return that satisfies the compiler, not a behavioral decision. Never `TODO()` — it throws at runtime, which is a crash, not a stub. A sibling's structure (naming, placement, style) is a template; its behavior (storage, defaulting, error handling, side effects) is not evidence for yours. If unsure, report it instead of guessing, along with anything needing a product decision.299. Implement every fix from step 8 directly: invoke `Skill(implementing-android-code)` first if the fix isn't purely mechanical, then commit with `Skill(bitwarden-delivery-tools:committing-changes)`.3010. Verify with the same compile task used in step 3.
bitwarden