From 4311b29d657aaa8c29f28962af322d95fd8ad2d9 Mon Sep 17 00:00:00 2001 From: Brandon McAnsh Date: Tue, 25 Aug 2026 15:33:35 -0400 Subject: [PATCH] docs(skills): cover the local contract override in /fetch-protos MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The skill said to stop when the contract change you need isn't released yet. Publishing is still human-gated and still the path for CI release builds, but it is no longer the way to try a field: `FLIPCASH_PROTO_LOCAL` makes `FlipcashAPI/Package.swift` swap its pinned requirements for path dependencies on the client checkouts. Adds the override to the pre-flight context, replaces the stop paragraph with the local loop and the Xcode environment caveat, and records that resolving in this mode drops both contract entries from the workspace `Package.resolved` — noise to restore, not a dependency change. --- .claude/skills/fetch-protos/SKILL.md | 39 +++++++++++++++++++++++++--- 1 file changed, 35 insertions(+), 4 deletions(-) diff --git a/.claude/skills/fetch-protos/SKILL.md b/.claude/skills/fetch-protos/SKILL.md index d0d5aabd0..c273d2882 100644 --- a/.claude/skills/fetch-protos/SKILL.md +++ b/.claude/skills/fetch-protos/SKILL.md @@ -26,7 +26,8 @@ happens in the package repos. ## Pre-flight context - Pinned versions: !`grep -E 'client-protocol' FlipcashAPI/Package.swift` -- Git status: !`git status --short FlipcashAPI/` +- Local override: !`echo "${FLIPCASH_PROTO_LOCAL:-none — building against the pins above}"` +- Git status: !`git status --short FlipcashAPI/ Code.xcodeproj/` ## Input @@ -55,9 +56,24 @@ gh release list --repo code-payments/ocp-client-protocol --limit 5 gh release list --repo code-payments/flipcash2-client-protocol --limit 5 ``` -If the contract change you want is not released yet, stop: it has to be synced and published -from the package repo first (see that repo's README — `scripts/sync-protos.sh`, then the -`publish.yml` workflow). Releasing is a deliberate, human-gated step; do not start it from here. +If the contract change you want is not released yet, do not reach for a release. Publishing is +for CI release builds, and it is human-gated — never start it from here. Build against the client +checkouts instead: + +```bash +export FLIPCASH_PROTO_LOCAL=~/dev/bmcreations/code +xed . +``` + +`FlipcashAPI/Package.swift` swaps both `.package(url:, exact:)` requirements for `.package(path:)` +when that variable names a directory holding `ocp-client-protocol/` and `flipcash2-client-protocol/`. +Xcode inherits the environment of whatever launched it, so it has to be started from the shell that +exported the variable — if Xcode was already open, relaunch it. Nothing tracked is edited to enter +this mode. + +Producing the unreleased change — editing a `.proto` and syncing it into the client repo — happens in +the client repo; the orchestrator's `/contract-change` skill drives both halves. In this mode skip +Step 2 and Step 3: there is no pin to bump, and the diff is whatever is in your checkout. Android pins the same two packages in its `gradle/libs.versions.toml`. The versions are not required to match across platforms, but a contract change that matters to both should land on @@ -74,6 +90,15 @@ xcodebuild -resolvePackageDependencies -project Code.xcodeproj -scheme Flipcash Show the resulting `Package.resolved` diff — it should change only the bumped package's `version` and `revision`. +If `FLIPCASH_PROTO_LOCAL` is set, resolving instead **drops** both contract entries from +`Code.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved`, because path +dependencies are not recorded there. That is noise rather than a version change — the pins are +`exact` — but restore the file before committing: + +```bash +git checkout -- Code.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved +``` + ### Step 3 — Diff and summarize changes The packages ship their generated Swift committed, so the API diff is readable directly: @@ -233,6 +258,12 @@ feat: scaffold service for new RPCs ## Never +- Cut a release of a client package just to try a change. Use the local override; release when the + change is settled and a build you do not control needs it. +- Commit a `Package.resolved` that lost its contract entries — that is the local override leaking, + not a dependency change. +- Leave `FLIPCASH_PROTO_LOCAL` exported once you are done. A later Xcode launched from that shell + quietly builds someone's working tree instead of the pinned release. - Patch generated code locally to work around a contract problem. It lives in the package repos; fix it there and cut a release. Update the wrapping `*Service.swift` instead when the gap is app-side. - Give a streaming RPC a deadline (`.unaryDefault`). Streaming passes `.defaults`. - Interpolate variables (especially base58/keys) into log message strings — variables go in `metadata`.