---
type: guidance
project: fidelity
status: active
updated: 2026-04-17
tags:
  - ios
  - cocoapods
  - dependencies
  - fidelity
---
# CocoaPods Dependency Management

## Goal

Help the agent reason correctly about CocoaPods behavior, private podspec repos, and release propagation in the Fidelity iOS ecosystem.

---

## Why This Matters Here

- CocoaPods is a core part of how XFlowSDK changes reach XFlowViewMaker, FTFrameworks, and Fid4.
- Many apparent SDK or consumer issues are actually dependency-resolution or published-podspec issues.
- The workspace should treat CocoaPods knowledge as part of normal investigation and release reasoning, not as an edge case.

---

## Fidelity-Specific Context

- XFlowSDK releases publish artifacts and podspec updates that downstream consumers adopt through CocoaPods.
- XFlowViewMaker, FTAccountOpen, FTTransfer, and Fid4 propagation all depend on correct podspec and resolver behavior.
- The effective dependency constraint can come from the published podspec repo layer, not only from the source repo that developers inspect first.
- Fid4 currently does not keep `Podfile.lock` in Git, which weakens reproducibility and makes published podspec changes more operationally significant.

---

## Agent Rules

- When a newly published dependency does not resolve in Fid4, check CocoaPods resolution before assuming the code change failed.
- Distinguish these layers:
  - source repo podspec or helper code
  - published private podspec repo
  - consumer `Podfile`
  - local/pipeline lockfile state
- Do not assume FTFrameworks source tells the whole truth about the active dependency graph.
- Treat private podspec repo edits as high-signal release-path behavior that may explain why local or pipeline resolution differs from expectations.
- When giving advice, separate:
  - what fixed the immediate unblock
  - what is healthy long-term dependency management

---

## CocoaPods Best-Practice Anchors

- CocoaPods podspecs are expected to declare dependency requirements explicitly.
- CocoaPods documentation recommends the optimistic operator `~>` because it provides version control without being overly restrictive.
- Overly restrictive dependency requirements can block compatibility.
- Removing dependency constraints entirely can weaken compatibility guarantees and make transitive resolution less predictable.
- `pod install` is the normal command after dependency-definition changes; `pod update` is for intentionally updating pod versions.
- `Podfile.lock` is important for reproducible installs and should normally be committed.

---

## Current Project Caution

- In this project, removing the XFlowViewMaker version reference from published `FTAccountOpen` and `FTTransfer` podspecs unblocked Fid4 resolution.
- That should be understood as the current operational fix, not automatically as the ideal dependency-management pattern.
- Because `Podfile.lock` is not committed in Fid4, broad podspec-repo edits can silently change future resolutions more than they should in a healthier CocoaPods setup.

---

## What Good Answers Should Include

- Whether the issue is in source code, published specs, or consumer resolution
- Whether `pod install`, `pod install --repo-update`, or `pod update` is the appropriate command for the stated goal
- Whether the current fix improves compatibility or only removes guardrails
- Whether the result is reproducible or vulnerable to future resolver drift
- Whether the advice is a short-term unblock or a durable recommendation