From 87a192bfd580b9095643aa1a3b3808d5b8ad4eeb Mon Sep 17 00:00:00 2001 From: russellwheatley Date: Fri, 31 Jul 2026 15:16:45 +0100 Subject: [PATCH 1/3] docs(okf): add agent knowledge bundle foundation Introduce the okf-bundle entry point, documentation/commit policy, and testing docs (command allowlist, change loop, validation, coverage, Auth emulator project). --- okf-bundle/documentation-policy.md | 66 ++++++ okf-bundle/index.md | 32 +++ okf-bundle/testing/agent-command-policy.md | 104 +++++++++ .../testing/change-authoring-workflow.md | 198 ++++++++++++++++++ okf-bundle/testing/coverage-design.md | 44 ++++ .../testing/firebase-testing-project.md | 30 +++ okf-bundle/testing/index.md | 10 + okf-bundle/testing/iteration-vocabulary.md | 87 ++++++++ okf-bundle/testing/running-tests.md | 149 +++++++++++++ okf-bundle/testing/validation-checklist.md | 132 ++++++++++++ 10 files changed, 852 insertions(+) create mode 100644 okf-bundle/documentation-policy.md create mode 100644 okf-bundle/index.md create mode 100644 okf-bundle/testing/agent-command-policy.md create mode 100644 okf-bundle/testing/change-authoring-workflow.md create mode 100644 okf-bundle/testing/coverage-design.md create mode 100644 okf-bundle/testing/firebase-testing-project.md create mode 100644 okf-bundle/testing/index.md create mode 100644 okf-bundle/testing/iteration-vocabulary.md create mode 100644 okf-bundle/testing/running-tests.md create mode 100644 okf-bundle/testing/validation-checklist.md diff --git a/okf-bundle/documentation-policy.md b/okf-bundle/documentation-policy.md new file mode 100644 index 0000000000..343369c0d6 --- /dev/null +++ b/okf-bundle/documentation-policy.md @@ -0,0 +1,66 @@ +--- +type: Reference +title: OKF documentation and commit policy +description: Canonical rules for durable vs ephemeral knowledge, commit messages, and post-update bundle consistency. +tags: [okf, documentation, policy, commits, work-queue] +timestamp: 2026-07-31T00:00:00Z +--- + +# OKF documentation and commit policy + +Single source of truth for OKF knowledge and commit wording. Other OKF docs/work queues link here; do not restate. + +## Durable vs ephemeral + +| Kind | Where it lives | What it contains | +|------|----------------|------------------| +| **Durable** | OKF reference docs (design, runbooks, registries, workflows) | Stable API names, module boundaries, SDK/tooling versions, verification **methods**, architecture, canonical commands | +| **Ephemeral** | Explicit **work-queue** docs only | Session phase/probe IDs, **planned commit subjects** (`commit_subject`), gate state, `next_work_type`, snapshot labels, dated banners, run counts | + +**Rules** + +1. General OKF docs get **durable only** updates: no phase IDs, **commit subjects**, session test counts, or gate snapshots. +2. Ephemeral state lives **only** in work queues. When an item closes, durable outcomes move to reference docs; queue rows may archive/delete. +3. Durable docs may link to a work queue for current status; do not duplicate ephemeral fields. + +## Commits as documentation + +We treat **git commits** as durable documentation: they are the canonical record of what changed, when, and why — for humans and agents reviewing history later, not only for the current PR thread. + +Commit messages use [Conventional Commits](https://www.conventionalcommits.org/) and describe durable product/process deliverables: what changed and why, not probe IDs, gates, test counts, or "phase X complete". + +Common scopes in this repo (non-exhaustive): `auth`, `database`, `firestore`, `storage`, `swiftui`, `ci`, `sample`, `docs`, `okf`. + +## Pull requests + +When a PR contains **exactly one commit**, the **PR title must match that commit's subject line exactly** (character-for-character). Multi-commit PRs use a summary title that describes the overall change set. + +Also follow [`PULL_REQUEST_TEMPLATE.md`](../PULL_REQUEST_TEMPLATE.md) and [`CONTRIBUTING.md`](../CONTRIBUTING.md) (CLA, feature parity with FirebaseUI-Android where the change is user-facing). + +## OKF update contract + +OKF markdown edits require an **independent bundle consistency pass**. Use a fresh context with: + +1. A short summary of what changed and which files were touched. +2. Instruction to scan the **entire** `okf-bundle/` tree. + +Confirm: + +| Check | Requirement | +|-------|-------------| +| **Canonical location** | Each topic has one owning doc; others link to it ([agent command policy](testing/agent-command-policy.md) for **all** agent shell commands; [change authoring](testing/change-authoring-workflow.md) for workflow/gates/frozen tree; [change authoring § validation evidence (blocking)](testing/change-authoring-workflow.md#validation-evidence-blocking); [running tests](testing/running-tests.md) for test command detail; [iteration vocabulary](testing/iteration-vocabulary.md) for term ids only; [change authoring § quality standards](testing/change-authoring-workflow.md#quality-standards) for review-findings resolution; [coverage design](testing/coverage-design.md) for coverage expectations; [SPM and CocoaPods workflow](packaging/spm-and-cocoapods-workflow.md) for distribution; [firebase testing project](testing/firebase-testing-project.md) for Auth emulator defaults; this file for doc/commit policy) | +| **DRY** | No duplicated procedures, policy paragraphs, or ephemeral snapshots outside work queues | +| **Link hygiene** | Cross-links resolve; indexes list canonical entry points | +| **Durability** | No ephemeral fields leaked into general reference docs | + +Fix violations before handoff/merge. Work-queue edits still follow this split. + +## Work-queue documents + +Work queues are **intentionally ephemeral**: phases, **commit subjects**, gates, active coordination. They are not policy or finalized registry/design homes. + +Work queues record **gates**, **`next_work_type`**, **`validation_tier`**, and **`commit_subject`** using field names and allowed values from [iteration vocabulary](testing/iteration-vocabulary.md). Gate semantics and workflow rules: [change authoring workflow](testing/change-authoring-workflow.md). They do **not** name agent roles, dispatch instructions, or session choreography — those are out of scope for the public repo. + +Record **`commit_subject`** (the planned Conventional Commit subject line) **before** `git commit`, in the same staged changeset as the item being memorialized. Do not record SHAs — they are unstable under history rewrite. After commit, the subject in git and in the queue must match character-for-character ([PR title rule](#pull-requests) for single-commit PRs). + +New work queues link here in frontmatter/opening section; do not copy policy inline. diff --git a/okf-bundle/index.md b/okf-bundle/index.md new file mode 100644 index 0000000000..e3d64ccbb3 --- /dev/null +++ b/okf-bundle/index.md @@ -0,0 +1,32 @@ +--- +okf_version: '0.1' +--- + +# FirebaseUI-iOS knowledge bundle + +Agent-oriented knowledge for this repository. Prefer these docs over improvised shell diagnostics or copying patterns from other FirebaseUI / React Native Firebase repos without re-deriving commands from this tree. + +- [Documentation/commit policy](documentation-policy.md) — durable vs ephemeral, commits as documentation, PR titles, OKF consistency + +# Testing + +- [Agent command policy](testing/agent-command-policy.md) — allowlisted shell commands (install, lint, unit, integration, UI, CocoaPods) +- [Change authoring workflow](testing/change-authoring-workflow.md) — verified change loop (unit-focused → area-focused review → commit); [§ validation evidence (blocking)](testing/change-authoring-workflow.md#validation-evidence-blocking) +- [Iteration vocabulary](testing/iteration-vocabulary.md) — work type, tier, and queue field identifiers +- [Running tests](testing/running-tests.md) — canonical SwiftUI and UIKit test commands, narrowing, emulator +- [Validation checklist](testing/validation-checklist.md) — lint, SPM package tests, CocoaPods module tests, samples, pod lint +- [Coverage design](testing/coverage-design.md) — where coverage is produced and how to treat it +- [Firebase testing project](testing/firebase-testing-project.md) — Auth emulator project id, ports, local vs CI + +# CI workflows + +- [CI workflows](ci-workflows/index.md) — GitHub Actions job map, Xcode/simulator pins, artifact triage + +# Packaging + +- [SPM and CocoaPods workflow](packaging/spm-and-cocoapods-workflow.md) — dual distribution rules, product matrix, release scripts +- [SPM / CocoaPods work queue](packaging/spm-cocoapods-work-queue.md) — ephemeral dual-distribution tracker + +# Packages + +- [Packages index](packages/index.md) — Auth SwiftUI, Database UI, Firestore UI, Storage UI diff --git a/okf-bundle/testing/agent-command-policy.md b/okf-bundle/testing/agent-command-policy.md new file mode 100644 index 0000000000..0a581ebbc3 --- /dev/null +++ b/okf-bundle/testing/agent-command-policy.md @@ -0,0 +1,104 @@ +--- +type: Reference +title: Agent command policy +description: Canonical allowlist for agent shell commands — install, lint, SwiftUI tests, UIKit CocoaPods tests, SPM builds. Supersedes improvised diagnostics. +tags: [testing, validation, agents, workflow, xcodebuild] +timestamp: 2026-07-31T00:00:00Z +--- + +# Agent command policy + +Single source for **which shell commands agents may run** in this repo. Test detail lives in [running tests](running-tests.md); this file owns the allowlist and bans. + +> If a command is not listed here (or linked from here as canonical), **do not run it** — including "diagnostic probes" suggested by log output, Xcode help, CocoaPods help, or other Firebase repos. + +## Agent rule (read first) + + + +1. Run **only** commands in the [registry](#canonical-registry) below (repo root unless noted). +2. Match the **distribution path** to the code you changed: SwiftUI / `Package.swift` → SPM + `./swiftui-tests.sh`; UIKit Database/Firestore/Storage modules → CocoaPods workspace + `./test.sh` (and SPM scheme build when `Package.swift` paths changed). See [SPM and CocoaPods workflow](../packaging/spm-and-cocoapods-workflow.md). +3. When a canonical command fails: read the **full** output, fix **product code** (or re-run the documented install step), re-run the **same** command. Do **not** switch invocation style. +4. Do **not** invent alternate destinations, schemes, or simulators from error strings — use the pins in [running tests](running-tests.md) / CI workflows. +5. Subagents (Task, explore, orchestrator): same rule — paste the [handoff block](#subagent-handoff) into every FirebaseUI-iOS task prompt. + +## Canonical registry + +| Intent | Command | Never use instead | +|--------|---------|-------------------| +| Ruby gems (CocoaPods path) | `bundle install` (repo root) | ad-hoc `gem install cocoapods` as the primary path when `Gemfile` exists | +| UIKit module pods | `cd FirebaseDatabaseUI\|FirebaseFirestoreUI\|FirebaseStorageUI && bundle exec pod install` | `pod install` without Bundler; editing `Podfile.lock` by hand to "fix" CI | +| UIKit module unit tests (one module) | `./test.sh FirebaseDatabaseUI` / `FirebaseFirestoreUI` / `FirebaseStorageUI` (after that module's `pod install`) | bare `xcodebuild` with a different scheme/workspace/destination than `test.sh` | +| UIKit modules local all-three | `./local_test.sh` | inventing a loop of `xcodebuild` flags that diverge from `local_test.sh` | +| SwiftUI Auth CI-local suite | `./swiftui-tests.sh` ([flags](running-tests.md#swiftui-auth-tests)) | hand-rolled `xcodebuild test` that skips `prepare-ios-simulator.sh` / emulator startup | +| SwiftFormat lint | `./lint-swift.sh` or `./swiftui-tests.sh --lint …` | `swiftformat` on arbitrary paths outside the script; inventing SwiftLint | +| SwiftFormat write | `./format-swift.sh` | formatting ObjC UIKit sources with SwiftFormat | +| SPM package list / scheme discover | `xcodebuild -list` (repo root) | assuming scheme names from other repos | +| SPM UIKit product compile check | `xcodebuild -scheme FirebaseDatabaseUI\|FirebaseFirestoreUI\|FirebaseStorageUI -sdk iphonesimulator -destination 'platform=iOS Simulator,OS=latest,name=iPhone 17 Pro'` (matches CI `spm` jobs) | random device names; building macOS/watchOS | +| SPM SwiftUI package unit tests | `./swiftui-tests.sh --unit` (preferred) — wraps `xcodebuild test -scheme FirebaseUI-Package` | `swift test` (this package is iOS-simulator backed) | +| Sample app builds | allowlisted sample `xcodebuild` in [running tests § samples](running-tests.md#sample-builds) | opening Xcode GUI as the agent gate | +| Podspec lint (touched pod) | `bundle exec pod lib lint .podspec` (matches CI `pod` jobs) | `pod trunk push` / release scripts during normal PR work | +| Release / staging | **human-only** — [`release.sh`](../../release.sh), [`release-swift.sh`](../../release-swift.sh), [`staging.sh`](../../staging.sh) | agents must not run trunk/push release scripts unless the user explicitly requests | + +### Host / toolchain assumptions + +- **Xcode:** CI pins **Xcode 26.2** for current workflows (see [CI workflows](../ci-workflows/index.md)). Prefer that version locally when available. +- **Default simulator name:** `iPhone 17 Pro` for module/SwiftUI tests; sample SwiftUI workflow uses `iPhone 17`. Prefer `./swiftui-tests.sh` / `./test.sh` over inventing destinations. +- **Simulator prep:** [`.github/workflows/scripts/prepare-ios-simulator.sh`](../../.github/workflows/scripts/prepare-ios-simulator.sh) is invoked by `swiftui-tests.sh` and CI — do not replace it with ad-hoc `simctl` boot loops unless debugging that script itself. + +## Forbidden (always) + +| Command / pattern | Why | +|-------------------|-----| +| `swift test` for this package | Targets are iOS; CI uses `xcodebuild test` on simulator | +| `npx` / `yarn` / `npm test` as product validation | Not this repo's test entrypoints (Firebase CLI/`npm` only for Auth emulator via documented scripts) | +| Invented SwiftLint / clang-format agent gates | Swift lint entrypoint is `./lint-swift.sh`; ObjC style is Google Objective-C guide via review, not an agent script today | +| `pod trunk push`, `./release.sh`, `./release-swift.sh` without explicit user request | Publishes artifacts | +| Changing `Package.resolved` / lockfiles to silence dependency errors without product justification | Masks real resolution issues | +| Copying RNFB `yarn tests:*` / Detox / Jet commands | Wrong stack | +| Parallel overlapping simulator test runs on one host | Flaky boots and port contention (Auth emulator `:9099`) | + +## Known traps + + + +### Dual distribution + +- Editing `FirebaseDatabaseUI/Sources/**` (etc.) affects **both** CocoaPods workspaces and SPM targets in `Package.swift`. Validate the path(s) you changed — see [SPM and CocoaPods workflow](../packaging/spm-and-cocoapods-workflow.md). +- SwiftUI Auth lives under `FirebaseSwiftUI/**` and is **SPM-first**; do not invent CocoaPods subspecs for those products. + +### Auth emulator + +- Integration/UI tests need Firebase CLI + Node; canonical start is inside `./swiftui-tests.sh` or `e2eTest/.../start-firebase-emulator.sh`. +- Defaults (project id, port): [firebase testing project](firebase-testing-project.md). Do not invent alternate emulator suites. + +### Workspace vs project + +- UIKit module tests use **`.xcworkspace`** after `pod install` (`./test.sh`). +- SwiftUI sample / e2e example use **`.xcodeproj`** under `samples/swiftui/` and `e2eTest/`. +- Package unit tests use scheme **`FirebaseUI-Package`** at repo root. + +## Subagent handoff + +Paste into Task / explore / work-queue prompts: + +```text +FirebaseUI-iOS agent command policy: okf-bundle/testing/agent-command-policy.md ONLY. +SwiftUI Auth tests: ./swiftui-tests.sh [--unit|--integration|--ui|--lint|--all] ONLY. +UIKit module tests: bundle exec pod install in module dir, then ./test.sh FirebaseDatabaseUI|FirebaseFirestoreUI|FirebaseStorageUI. +Lint Swift: ./lint-swift.sh (or ./swiftui-tests.sh --lint …). Format: ./format-swift.sh. +Never: swift test, yarn/detox/jet, invented xcodebuild destinations, pod trunk / release-*.sh without explicit user request. +On failure: fix product code, re-run the same canonical command. +Gate close / push: return validation evidence per okf-bundle/testing/change-authoring-workflow.md#validation-evidence-blocking. +``` + +## Related docs + +| Topic | Owner | +|-------|--------| +| Test commands, emulator, narrowing | [running-tests.md](running-tests.md) | +| Handoff validation sequence | [validation-checklist.md](validation-checklist.md) | +| Work types and gates | [change-authoring-workflow.md](change-authoring-workflow.md) | +| Doc / commit policy | [documentation-policy.md](../documentation-policy.md) | +| SPM vs CocoaPods | [spm-and-cocoapods-workflow.md](../packaging/spm-and-cocoapods-workflow.md) | +| Auth emulator project / ports | [firebase-testing-project.md](firebase-testing-project.md) | diff --git a/okf-bundle/testing/change-authoring-workflow.md b/okf-bundle/testing/change-authoring-workflow.md new file mode 100644 index 0000000000..ef7d635ff2 --- /dev/null +++ b/okf-bundle/testing/change-authoring-workflow.md @@ -0,0 +1,198 @@ +--- +type: Reference +title: Change authoring workflow +description: Canonical loop for verified product changes — baseline, unit-focused implementation, area-focused review, documentation, commit, and pre-merge validation. +tags: [testing, validation, workflow, implementation, review] +timestamp: 2026-07-31T00:00:00Z +--- + +# Change authoring workflow + +Single source for **how to author and verify a product change** in FirebaseUI-iOS (bug fix, feature, parity, coverage). Module docs add artifacts; work queues add ephemeral gate state — neither restates this loop. + +**Policy:** [OKF documentation and commit policy](../documentation-policy.md). **Terms:** [iteration vocabulary](iteration-vocabulary.md). + +## Primary loop + +```mermaid +flowchart TD + START([Pick change scope]) --> GA{Need feasibility /
semantics check?} + GA -->|yes| GAP["gap-analysis
tier: none"] + GA -->|no| BC{Need before snapshot
or area baseline?} + GAP --> BC + + BC -->|yes| BASE["baseline-capture
tier: area-focused"] + BC -->|no| IMPL + BASE --> IMPL + + IMPL["implementation
tier: unit-focused"] + IMPL --> IG{implementation gate
green?} + IG -->|no| IMPL + IG -->|yes| REV + + REV["independent-review
tier: area-focused
frozen tree"] + REV --> RG{all findings
resolved?} + RG -->|any unresolved| IMPL + RG -->|yes| DOC + + DOC{User-facing or
OKF durable updates?} + DOC -->|yes| DOCS["documentation
tier: none"] + DOC -->|no| COMMIT + DOCS --> COMMIT + + COMMIT["commit
tier: none"] + COMMIT --> PM{Branch ready
to merge?} + PM -->|yes| FULL["pre-merge-validation
tier: full"] + PM -->|no| END([Hand off / next item]) + FULL --> END +``` + +## Work types + +| Work type | When | Validation tier | Product edits | Commit | +|-----------|------|-----------------|---------------|--------| +| `gap-analysis` | Unclear feasibility, API shape, provider support | none | read-only | no | +| `baseline-capture` | Need before metrics or area suite baseline | `area-focused` | local narrowing OK | no | +| `implementation` | Author fix/feature + tests | `unit-focused` | yes | no | +| `independent-review` | Verify frozen diff | `area-focused` | no — [frozen tree](#frozen-tree) | no | +| `documentation` | User docs + durable OKF updates | none | docs only | no | +| `commit` | Gates closed for the item | none | staging only | yes | +| `pre-merge-validation` | Branch merge gate | `full` | revert narrowing first | no | + +**Commands per work type:** [validation checklist](validation-checklist.md) — link only; do not duplicate here. + +## Validation tiers + +Tier id strings: [iteration vocabulary § validation tier identifiers](iteration-vocabulary.md#validation-tier-identifiers). + +| Tier | Intent | Typical commands | +|------|--------|------------------| +| `unit-focused` | Fast loop while editing | Touched-area only: e.g. `./swiftui-tests.sh --unit` or `./test.sh FirebaseDatabaseUI`; `./lint-swift.sh` when Swift touched | +| `area-focused` | Full suite for the change area | SwiftUI Auth: `./swiftui-tests.sh --lint --all`. UIKit module: `./test.sh ` + SPM scheme build for that product when sources shared with `Package.swift` | +| `full` | Pre-merge / CI-equivalent | All suites affected by the branch + sample builds when samples/`Package.swift`/podspecs touched — [validation checklist](validation-checklist.md) | + +**Command rule:** Agents run **only** [agent command policy](agent-command-policy.md) allowlisted commands — no improvised `xcodebuild` / `pod` / `swift test` probes. + +## Gates + +| Gate | Closes when | +|------|-------------| +| `implementation` | `implementation` work type complete — code plus **unit-focused** checks green for every required path ([distribution path gate](running-tests.md#distribution-path-gate-blocking)); lint green on the diff when applicable | +| `review` | `independent-review` complete — **area-focused** checks green on frozen tree; applicable [validation checklist](validation-checklist.md) rows green; **every review finding resolved** ([§ quality standards](#quality-standards)) | +| `commit` | Durable commit exists for the item **after** prior gates closed with [recorded evidence](#validation-evidence-blocking) | + +**Trust rule:** Code on disk or in git with `review` still **open** is unverified until `independent-review` closes the gate. + +Any unresolved review finding returns the item to **`implementation`** (`unit-focused`), then repeats **`independent-review`** (`area-focused`). + + + +### Validation evidence (blocking) + +Gates close **only** when **recorded evidence** shows the required validation tier ran and passed. Assumed green, implementer summaries without exit codes, or "tests passed earlier" without a log path **do not** close a gate. + +| Gate | Minimum evidence (record in work-queue notes or review handoff) | +|------|------------------------------------------------------------------| +| **`implementation`** | Canonical command(s) + **exit codes**; log path when using `swiftui-tests.sh` / `xcodebuild` tees; **`./lint-swift.sh` exit 0** when Swift under its paths changed | +| **`review`** | Frozen-tree re-run of area-focused checklist; coverage notes when enabled ([coverage design](coverage-design.md)); sample/`pod lib lint` rows when those surfaces changed | +| **`commit`** | Prior gates closed **with evidence**; no temporary `#if DEBUG` test skips or focused-only hacks staged | +| **Publication** (`git push`, PR refresh) | **`review` gate closed on the exact commits being published**; evidence still valid (no product edits since last area-focused run) | + + + +### Forbidden shortcuts + +- **`git commit`** while the current work type's validation tier is incomplete or evidence is missing. +- **`git push` / PR update** claiming remediation or review-green **without** fresh area-focused evidence after the last product edit on the published commits. +- **History rewrite** (rebase, amend stack) **without** re-running validation for the rewritten scope — prior green results are **invalid**. +- **Self-accepted** parity or coverage gaps — only [acceptable exceptions](#acceptable-exceptions) with user confirmation or intractability evidence in durable OKF. + +## Quality standards + + + +### Acceptable exceptions + +Only two things may be documented and tracked instead of fixed. **Both require the user's explicit acceptance and confirmation plus a recorded rationale** — an agent or reviewer may not grant either on its own. + +1. **Intractable-limitation bar.** Gap caused by an intractable technical limitation of the language, platform SDK, compiler, or toolchain, shown with evidence (cited by version). +2. **User-accepted deferral.** Gap is addressable, but the user explicitly defers it with a documented rationale. + +Anything else is drift or a defect: + +- **If code can be authored, a test that exercises it can be authored** — otherwise it is dead code; delete it, do not document it. +- Convenience, time pressure, or "low risk" carry weight **only** through an explicit user-accepted deferral. + + + +### Review findings — resolve, do not defer + +`independent-review` classifies findings **critical / serious / minor / nit**. The **`review` gate closes only when every finding — including minor and nit — is resolved by a fix**, unless covered by an [acceptable exception](#acceptable-exceptions). "Green with minors" is not green. + +## Frozen tree + +Required for **`independent-review`** and for any suite run that closes the **`review`** gate: + +- No edits to product sources (`FirebaseSwiftUI/**`, `Firebase*UI/**`, `Package.swift`, podspecs, e2e/sample sources under test) during the run. +- Wait for or cancel in-flight runs before editing again. + +Keep **`implementation`** and **`independent-review`** in separate passes. + +## Host rule + +On a shared dev host during change authoring: + +- One heavyweight simulator suite at a time (do not overlap `./swiftui-tests.sh` integration/UI with `./test.sh` on the same simulator if contention appears). +- Auth emulator: one listener on `:9099` — prefer letting `./swiftui-tests.sh` manage lifecycle. +- Use only [canonical test commands](running-tests.md). + +## `implementation` inner loop + +```mermaid +flowchart TD + P1[Edit product code + tests] + P2[Lint if Swift paths touched] + P3{Area?} + P3 -->|SwiftUI Auth| P4["./swiftui-tests.sh --unit or narrower"] + P3 -->|UIKit module| P5["pod install + ./test.sh Module"] + P4 --> P6{Green?} + P5 --> P6 + P6 -->|no| P1 + P6 -->|yes| DONE([Close implementation gate]) + P1 --> P2 --> P3 +``` + +## `independent-review` + +On a **frozen tree**: + +1. Revert any temporary test focusing / skips. +2. Run **area-focused** suite for the change area ([running tests](running-tests.md)). +3. Run applicable [validation checklist](validation-checklist.md) rows (lint, SPM path, samples, pod lint as needed). +4. Outcome closes **review gate** or returns to **`implementation`**. + +## `commit` + +- One focused commit per item when gates close. +- **Evidence required:** [§ validation evidence](#validation-evidence-blocking). +- **Work queue:** before `git commit`, set the row's `commit_subject` to the commit's subject line, close `commit_gate`, and stage the queue doc **in the same commit** as the product change ([documentation policy § work queues](../documentation-policy.md#work-queue-documents)). Do not record SHAs in queue docs. + +```bash +git status +git diff --stat +``` + +## Feature parity + +User-facing Auth/UI features should stay coordinated with [FirebaseUI-Android](https://github.com/firebase/FirebaseUI-Android) where parity applies ([`CONTRIBUTING.md`](../../CONTRIBUTING.md)). Record parity gaps as durable module notes or accepted exceptions — do not silently ship one-platform-only behavior for shared product surface. + +## Related docs + +| Topic | Document | +|-------|----------| +| Term ids and queue field schema | [iteration-vocabulary.md](iteration-vocabulary.md) | +| Test commands | [running-tests.md](running-tests.md) | +| Validation commands | [validation-checklist.md](validation-checklist.md) | +| Coverage policy | [coverage-design.md](coverage-design.md) | +| Distribution | [spm-and-cocoapods-workflow.md](../packaging/spm-and-cocoapods-workflow.md) | +| Auth emulator project | [firebase-testing-project.md](firebase-testing-project.md) | diff --git a/okf-bundle/testing/coverage-design.md b/okf-bundle/testing/coverage-design.md new file mode 100644 index 0000000000..ff2da66ec5 --- /dev/null +++ b/okf-bundle/testing/coverage-design.md @@ -0,0 +1,44 @@ +--- +type: Reference +title: Coverage design +description: How FirebaseUI-iOS produces coverage and how agents should treat coverage evidence. +tags: [testing, coverage, xcodebuild] +timestamp: 2026-07-31T00:00:00Z +--- + +# Coverage design + +This repo enables Xcode code coverage on SwiftUI Auth CI jobs (`-enableCodeCoverage YES` with `.xcresult` bundles). It does **not** currently publish a Codecov-style merge gate comparable to React Native Firebase. Treat coverage as a **signal for review**, not a numeric CI pass/fail owned by OKF. + +## Where coverage is produced + +| Suite | How | Artifact | +|-------|-----|----------| +| SPM package unit (`FirebaseUI-Package`) | `./swiftui-tests.sh --unit` / CI `unit-tests` job | `FirebaseSwiftUIPackageTests.xcresult` | +| Integration | `./swiftui-tests.sh --integration` | `e2eTest/.../FirebaseSwiftUIExampleTests.xcresult` | +| UI | `./swiftui-tests.sh --ui` | `e2eTest/.../FirebaseSwiftUIExampleUITests.xcresult` | +| UIKit CocoaPods module tests | `./test.sh ` (CI module workflows) | Xcode test result under the module workspace run | + +Inspect `.xcresult` in Xcode or with `xcrun xccov` when investigating gaps. Do not invent a parallel coverage toolchain. + +## Expectations (policy) + + + +1. New or changed behavior should ship with tests at the appropriate layer (package unit vs integration vs UI vs UIKit XCTest). +2. Before closing **`review`** on non-trivial product diffs, skim coverage / failing regions for the touched files when an `.xcresult` exists — investigate reachable untsted lines ([change authoring § quality standards](change-authoring-workflow.md#quality-standards)). +3. Do not claim "100% coverage required" as a repo-wide gate unless CI grows an explicit threshold; do not skip writing tests because no Codecov gate exists. + + + +## Coverage evidence package + +When closing `review` on SwiftUI Auth or UIKit module product code, attach a short note: + +```markdown +| Surface | Suite | Result | Notes | +|---------|-------|--------|-------| +| | unit / integration / UI / uikit | pass + .xcresult path | gaps investigated: … | +``` + +If coverage was not collected (tooling failure), say so explicitly — do not imply it ran. diff --git a/okf-bundle/testing/firebase-testing-project.md b/okf-bundle/testing/firebase-testing-project.md new file mode 100644 index 0000000000..9632eef7be --- /dev/null +++ b/okf-bundle/testing/firebase-testing-project.md @@ -0,0 +1,30 @@ +--- +type: Reference +title: Firebase testing project +description: Auth emulator project id, ports, and local vs CI usage for FirebaseUI-iOS SwiftUI tests. +tags: [testing, emulator, firebase, auth] +timestamp: 2026-07-31T00:00:00Z +--- + +# Firebase testing project + +Canonical notes for the Firebase project / emulator used by SwiftUI Auth integration and UI tests. Command ownership stays in [agent command policy](agent-command-policy.md) and [running tests](running-tests.md). + +## Defaults + +| Setting | Value | +|---------|-------| +| Firebase project id | `flutterfire-e2e-tests` | +| Override | `FIREBASE_PROJECT=` when invoking `./swiftui-tests.sh` | +| Emulator | Auth only (`firebase emulators:start --only auth`) | +| Readiness probe | `http://localhost:9099` | +| Host app config | `e2eTest/FirebaseSwiftUIExample/FirebaseSwiftUIExample/` (`firebase.json`, `start-firebase-emulator.sh`) | + +## Local vs CI + +| Context | How emulator starts | +|---------|---------------------| +| Local | Prefer `./swiftui-tests.sh --integration` / `--ui` (starts or reuses emulator) | +| CI | [`.github/workflows/swiftui-auth.yml`](../../.github/workflows/swiftui-auth.yml) runs `start-firebase-emulator.sh` in the example app directory | + +Do not invent alternate emulator suites or project ids for agent gates. UIKit Database/Firestore/Storage module XCTest suites do **not** use this Auth emulator path. diff --git a/okf-bundle/testing/index.md b/okf-bundle/testing/index.md new file mode 100644 index 0000000000..04c121f8c9 --- /dev/null +++ b/okf-bundle/testing/index.md @@ -0,0 +1,10 @@ +# Testing + +* [Agent command policy](agent-command-policy.md) — **read before any shell command** (Ruby/CocoaPods, SwiftFormat, `swiftui-tests.sh`, `test.sh`, allowlisted `xcodebuild`) +* [Documentation/commit policy](../documentation-policy.md) — durable vs ephemeral, OKF scan +* [Change authoring workflow](change-authoring-workflow.md) — verified product change loop (unit-focused → area-focused review → commit); [§ quality standards](change-authoring-workflow.md#quality-standards); [§ validation evidence (blocking)](change-authoring-workflow.md#validation-evidence-blocking) +* [Iteration vocabulary](iteration-vocabulary.md) — work type, tier, and queue field identifiers +* [Running tests](running-tests.md) — canonical SwiftUI / UIKit test commands; start here for `swiftui-tests.sh` and `test.sh` +* [Validation checklist](validation-checklist.md) — handoff command sequence +* [Coverage design](coverage-design.md) — coverage production and evidence expectations +* [Firebase testing project](firebase-testing-project.md) — Auth emulator project id, ports, local vs CI diff --git a/okf-bundle/testing/iteration-vocabulary.md b/okf-bundle/testing/iteration-vocabulary.md new file mode 100644 index 0000000000..46a123d0b6 --- /dev/null +++ b/okf-bundle/testing/iteration-vocabulary.md @@ -0,0 +1,87 @@ +--- +type: Reference +title: Iteration vocabulary +description: Identifier glossary and work-queue field schema for OKF — not workflow rules or commands. +tags: [testing, validation, workflow, work-queue] +timestamp: 2026-07-31T00:00:00Z +--- + +# Iteration vocabulary + +Glossary of **string identifiers** and **work-queue field names** used across OKF. This doc does not define procedures, gate rules, or test commands — each topic has one owning doc; others link. + +**Policy:** [OKF documentation and commit policy](../documentation-policy.md). + +| Topic | Owner | +|-------|--------| +| Change loop, gates, frozen tree, host rule | [change authoring workflow](change-authoring-workflow.md) | +| **All agent shell commands** | [agent command policy](agent-command-policy.md) | +| Test command detail, emulator, narrowing | [running tests](running-tests.md) | +| Validation command sequence | [validation checklist](validation-checklist.md) | +| Work-queue gate snapshots | Package/module work queues (ephemeral) | + +## Work type identifiers + +| Work type | Brief meaning | +|-----------|---------------| +| `gap-analysis` | Read-only feasibility / semantics check | +| `baseline-capture` | Record before snapshots or baselines | +| `implementation` | Author product code and tests | +| `independent-review` | Verify a frozen diff | +| `documentation` | User docs and durable OKF updates | +| `commit` | Stage and create one commit | +| `pre-merge-validation` | Branch-wide merge gate | + +When to use each work type, validation tier, edit policy, and commit rules: [change authoring § work types](change-authoring-workflow.md#work-types). + +## Validation tier identifiers + +| Tier id | Brief meaning | +|---------|---------------| +| `unit-focused` | Fast validation while product code is changing | +| `area-focused` | Full loaded module/area suite for the change | +| `full` | Unfocused — all relevant modules and CI-equivalent suites | + +Test scope per tier: [change authoring § validation tiers](change-authoring-workflow.md#validation-tiers), [running tests § validation tiers](running-tests.md#validation-tiers). + +## Gate identifiers + +Work queues use these **field names** (values: `open` | `closed`): + +| Field | Tracks | +|-------|--------| +| `implementation_gate` | `implementation` work type complete | +| `review_gate` | `independent-review` work type complete | +| `commit_gate` | Durable commit exists for the item **after** prior gates closed with [validation evidence](change-authoring-workflow.md#validation-evidence-blocking) | + +What closes each gate: [change authoring § gates](change-authoring-workflow.md#gates). + +`commit_gate` closes when a durable commit exists whose subject matches the row's `commit_subject`, **after** `implementation_gate` and `review_gate` closed with validation evidence. + +Items may also be marked **`blocked`** when a dependency gate is open elsewhere. + +## Work-queue fields + +Ephemeral work queues may record: + +| Field | Allowed values / meaning | +|-------|--------------------------| +| `next_work_type` | A [work type identifier](#work-type-identifiers) | +| `validation_tier` | `unit-focused` \| `area-focused` \| `full` | +| `platform` | Optional scope (this repo is iOS-only; use module ids e.g. `swiftui-auth`, `database-ui`) | +| `implementation_gate` | `open` \| `closed` | +| `review_gate` | `open` \| `closed` | +| `commit_gate` | `open` \| `closed` | +| `commit_subject` | Planned or landed **first line** of the item's focused commit (Conventional Commits subject). Set **before** `git commit`; must match the commit that closes `commit_gate`. Do not record SHAs. | +| `blocked` | Item or dependency blocked until named gate closes | + +Queues record **state**, not who executes the work. + +## Related docs + +| Topic | Document | +|-------|----------| +| **Change authoring loop** | [change-authoring-workflow.md](change-authoring-workflow.md) | +| Test commands | [running-tests.md](running-tests.md) | +| Validation commands | [validation-checklist.md](validation-checklist.md) | +| Doc/commit policy | [documentation-policy.md](../documentation-policy.md) | diff --git a/okf-bundle/testing/running-tests.md b/okf-bundle/testing/running-tests.md new file mode 100644 index 0000000000..f398759934 --- /dev/null +++ b/okf-bundle/testing/running-tests.md @@ -0,0 +1,149 @@ +--- +type: Reference +title: Running tests +description: Canonical SwiftUI Auth and UIKit module test commands, emulator, narrowing, and distribution-path gate. +tags: [testing, xcodebuild, emulator, swiftui, cocoapods] +timestamp: 2026-07-31T00:00:00Z +--- + +# Running tests + +Canonical **how to invoke** tests in this repo. Allowlist ownership: [agent command policy](agent-command-policy.md). Do not restate the allowlist here. + + + +## Agent rule (read first) + +1. Prefer wrapper scripts (`./swiftui-tests.sh`, `./test.sh`, `./local_test.sh`, `./lint-swift.sh`) over hand-built `xcodebuild` lines. +2. When you must call `xcodebuild` directly, match **scheme / workspace-or-project / destination** to CI or to the wrappers above. +3. On failure: fix product code (or documented setup), re-run the **same** command. + +## Validation tiers + + + +| Tier | SwiftUI Auth (`FirebaseSwiftUI/**`, `Package.swift` SwiftUI products) | UIKit modules (`FirebaseDatabaseUI`, `FirebaseFirestoreUI`, `FirebaseStorageUI`) | +|------|------------------------------------------------------------------------|----------------------------------------------------------------------------------| +| `unit-focused` | `./swiftui-tests.sh --unit` (optional `--lint`) | `bundle exec pod install` in module dir → `./test.sh ` | +| `area-focused` | `./swiftui-tests.sh --lint --all` | `./test.sh ` **and** SPM scheme build for that product if `Package.swift` shares sources | +| `full` | area-focused + sample SwiftUI build + any touched CI path | all three modules as needed + sample UIKit builds + `pod lib lint` for touched podspecs | + +Work-type mapping: [change authoring](change-authoring-workflow.md). + + + +## Distribution path gate (blocking) + +Sources under `FirebaseDatabaseUI/Sources`, `FirebaseFirestoreUI/Sources`, and `FirebaseStorageUI/Sources` are consumed by **CocoaPods workspaces and SPM targets**. Closing `implementation` / `review` for those trees requires the CocoaPods test path **and**, when `Package.swift` or shared headers changed, the CI-equivalent SPM scheme build. + +SwiftUI Auth sources under `FirebaseSwiftUI/**` are **SPM-only** for product delivery — use `./swiftui-tests.sh`, not CocoaPods. + +Details: [SPM and CocoaPods workflow](../packaging/spm-and-cocoapods-workflow.md). Emulator project: [firebase testing project](firebase-testing-project.md). + +## SwiftUI Auth tests + + + +Local equivalent of [`.github/workflows/swiftui-auth.yml`](../../.github/workflows/swiftui-auth.yml): + +```bash +./swiftui-tests.sh # unit + integration + UI (default) +./swiftui-tests.sh --unit +./swiftui-tests.sh --integration --ui +./swiftui-tests.sh --lint --all +./swiftui-tests.sh --device "iPhone 17 Pro" --ui +FIREBASE_PROJECT="my-firebase-project" ./swiftui-tests.sh --integration +``` + +| Flag | What runs | +|------|-----------| +| `--unit` | `xcodebuild test -scheme FirebaseUI-Package` (package unit tests) | +| `--integration` | `FirebaseSwiftUIExampleTests` with Auth emulator | +| `--ui` | `FirebaseSwiftUIExampleUITests` build-for-testing + test-without-building | +| `--lint` | `./lint-swift.sh` before selected tests | +| `--device NAME` | Simulator device name (default `iPhone 17 Pro`) | + +**Requirements for `--integration` / `--ui`:** Firebase CLI, Node.js, npm. Emulator listens on `http://localhost:9099`. Default project: `flutterfire-e2e-tests`. + +**Logs / result bundles** (written by the script / CI): + +| Suite | Log (typical) | `.xcresult` | +|-------|---------------|-------------| +| Package unit | `FirebaseSwiftUIPackageTests.log` | `FirebaseSwiftUIPackageTests.xcresult` | +| Integration | `e2eTest/FirebaseSwiftUIExample/FirebaseSwiftUIExampleTests.log` | `…/FirebaseSwiftUIExampleTests.xcresult` | +| UI | `e2eTest/FirebaseSwiftUIExample/FirebaseSwiftUIExampleUITests.log` | `…/FirebaseSwiftUIExampleUITests.xcresult` | + +Project id / port defaults: [firebase testing project](firebase-testing-project.md). + +### Narrowing (local only) + +- Prefer `--unit` during `unit-focused` implementation when only package logic changed. +- Prefer `--integration` or `--ui` alone when diagnosing that layer. +- **Never commit** permanent skips that disable CI-equivalent coverage without an [acceptable exception](change-authoring-workflow.md#acceptable-exceptions). +- Xcode test focusing (`testFoo` only via IDE) is fine locally; agent gates should still re-run the scripted suite for the tier. + +## UIKit module tests (CocoaPods) + + + +```bash +cd FirebaseDatabaseUI # or FirebaseFirestoreUI / FirebaseStorageUI +bundle exec pod install +cd .. +./test.sh FirebaseDatabaseUI +``` + +`./test.sh` runs `xcodebuild` against `$module.xcworkspace` / scheme `$module`, iPhone simulator destination pinned in the script (`iPhone 17 Pro` as of authoring). + +All three locally (also updates pod repos): + +```bash +./local_test.sh +``` + +**Note:** `local_test.sh` pins **`iPhone 16 Pro`**, while `./test.sh` and CI module/`spm` jobs pin **`iPhone 17 Pro`**. Prefer `./test.sh` for agent gates so the destination matches CI. + +## SPM scheme builds (UIKit products) + +CI `spm` jobs compile SPM products without the CocoaPods workspace: + +```bash +xcodebuild -scheme FirebaseDatabaseUI -sdk iphonesimulator \ + -destination 'platform=iOS Simulator,OS=latest,name=iPhone 17 Pro' +``` + +Same pattern for `FirebaseFirestoreUI` and `FirebaseStorageUI`. + +## Sample builds + + + +Match [`.github/workflows/sample.yml`](../../.github/workflows/sample.yml) when samples or shared packaging change: + +```bash +# SwiftUI sample +cd samples/swiftui/FirebaseSwiftUISample +xcodebuild -project FirebaseSwiftUISample.xcodeproj -scheme FirebaseSwiftUISample \ + -sdk iphonesimulator -destination 'platform=iOS Simulator,OS=latest,name=iPhone 17' \ + clean build ONLY_ACTIVE_ARCH=YES +``` + +UIKit samples under `samples/swift` / `samples/objc` follow the same workflow file (CocoaPods install then `xcodebuild`; the Swift demo runs **`clean build test`**, ObjC runs **`clean build`**) — copy flags from CI rather than inventing them. See [samples CI](../ci-workflows/samples.md). + +## Lint / format + +```bash +./lint-swift.sh # CI format-check job +./format-swift.sh # rewrite SwiftFormat paths +``` + +Paths covered: `FirebaseSwiftUI/`, `samples/swiftui/FirebaseSwiftUISample/`, `e2eTest/`, `Package.swift`. + +## Related docs + +| Topic | Document | +|-------|----------| +| Allowlist / bans | [agent-command-policy.md](agent-command-policy.md) | +| Handoff sequence | [validation-checklist.md](validation-checklist.md) | +| CI job map | [../ci-workflows/index.md](../ci-workflows/index.md) | +| Coverage | [coverage-design.md](coverage-design.md) | diff --git a/okf-bundle/testing/validation-checklist.md b/okf-bundle/testing/validation-checklist.md new file mode 100644 index 0000000000..e8d1919dc5 --- /dev/null +++ b/okf-bundle/testing/validation-checklist.md @@ -0,0 +1,132 @@ +--- +type: Reference +title: Validation checklist +description: Canonical command sequence for validating FirebaseUI-iOS changes and handoff. +tags: [testing, validation, lint, xcodebuild, cocoapods] +timestamp: 2026-07-31T00:00:00Z +--- + +# Validation checklist + +Validation commands for development/handoff. Other docs link here; do not restate. + +Coverage expectations: [coverage design](coverage-design.md). + +## When to run what + +Work types and tiers: [change authoring workflow](change-authoring-workflow.md). Term ids: [iteration vocabulary](iteration-vocabulary.md). + +| Work type | Scope | Shortcuts | +|-----------|-------|-----------| +| `gap-analysis` | Read APIs, `Package.swift`, podspecs, provider docs | n/a | +| `baseline-capture` | Area suite for the module | **area-focused**; no permanent skips | +| `implementation` | Unit-focused suite for touched area + lint when Swift touched | **unit-focused**; see [running tests](running-tests.md) | +| `independent-review` | Area-focused full area suite + applicable rows below | **area-focused**; [frozen tree](change-authoring-workflow.md#frozen-tree) | +| `pre-merge-validation` | All CI-equivalent suites affected by the branch | **full** tier | + +## Lint and formatting + + + +When `FirebaseSwiftUI/**`, `samples/swiftui/**`, `e2eTest/**`, or `Package.swift` change: + +```bash +./lint-swift.sh +# or +./swiftui-tests.sh --lint --unit +``` + +To apply formatting: + +```bash +./format-swift.sh +``` + +ObjC UIKit modules: follow [Google Objective-C style](https://google.github.io/styleguide/objcguide.xml) in review; there is no agent SwiftFormat gate for those trees today. + +## SwiftUI Auth / SPM package + +```bash +./swiftui-tests.sh --unit # package unit tests +./swiftui-tests.sh --integration # emulator + integration +./swiftui-tests.sh --ui # emulator + UI tests +./swiftui-tests.sh --lint --all # area-focused / pre-merge for Auth +``` + +## UIKit modules (CocoaPods) + +From repo root, after `bundle install` once: + +```bash +cd FirebaseDatabaseUI && bundle exec pod install && cd .. +./test.sh FirebaseDatabaseUI +# repeat for FirebaseFirestoreUI / FirebaseStorageUI when those trees change +``` + +## SPM compile check (shared UIKit sources) + +When `Package.swift` or shared UIKit sources change: + +```bash +xcodebuild -scheme FirebaseDatabaseUI -sdk iphonesimulator \ + -destination 'platform=iOS Simulator,OS=latest,name=iPhone 17 Pro' +# FirebaseFirestoreUI / FirebaseStorageUI as needed +``` + +## Podspec lint + +When a podspec or its packaged sources change: + +```bash +bundle install +bundle exec pod lib lint FirebaseDatabaseUI.podspec +# FirebaseFirestoreUI.podspec / FirebaseStorageUI.podspec / FirebaseUI.podspec as needed +``` + +Do **not** run `pod trunk push` / `./release.sh` as part of ordinary validation. + +## Samples + +When `samples/**` or packaging that samples consume changes, run the matching jobs from [running tests § samples](running-tests.md#sample-builds) / [sample CI](../ci-workflows/samples.md). + +## OKF bundle review + +Before handoff, follow [OKF policy](../documentation-policy.md#okf-update-contract): + +1. Update relevant `okf-bundle/packages//` docs with durable learnings. +2. Check `okf-bundle/testing/` and `okf-bundle/packaging/` for conflicts with verified behavior; fix drift. +3. Run independent scan for canonical ownership, DRY refs, link hygiene, durability. + + + +## Validation evidence package (blocking) + +Before closing **`implementation_gate`**, **`review_gate`**, **`commit_gate`**, or publishing (`git push` / PR update), record evidence per [change authoring § validation evidence](change-authoring-workflow.md#validation-evidence-blocking). Minimum template: + +```markdown +| Step | Command | Exit | Evidence | +|------|---------|------|----------| +| lint (Swift) | ./lint-swift.sh | 0 | when SwiftFormat paths touched | +| swiftui unit | ./swiftui-tests.sh --unit | 0 | when FirebaseSwiftUI / Package SwiftUI products touched | +| swiftui integration | ./swiftui-tests.sh --integration | 0 | when auth flows / e2eTest touched | +| swiftui UI | ./swiftui-tests.sh --ui | 0 | when UI / UITest surface touched | +| uikit module | ./test.sh FirebaseDatabaseUI | 0 | when that module touched | +| spm scheme | xcodebuild -scheme FirebaseDatabaseUI … | 0 | when Package.swift / shared sources touched | +| pod lib lint | bundle exec pod lib lint … | 0 | when podspec touched | +| sample build | (CI-equivalent xcodebuild) | 0 | when samples touched | +``` + +**History rewrite invalidates** prior rows — re-run and replace the table after amend/rebase. + +## Handoff checklist + +- [ ] [Distribution path gate](running-tests.md#distribution-path-gate-blocking) satisfied for UIKit shared sources +- [ ] `./lint-swift.sh` when SwiftFormat-covered paths changed +- [ ] SwiftUI: appropriate `./swiftui-tests.sh` flags green +- [ ] UIKit: `./test.sh ` green for each touched module +- [ ] SPM scheme build when `Package.swift` / shared UIKit sources changed +- [ ] `pod lib lint` when podspecs changed +- [ ] Sample builds when samples changed +- [ ] [Validation evidence package](#validation-evidence-package) recorded +- [ ] OKF bundle reviewed/updated per § above +- [ ] Feature parity considered for user-facing Auth/UI ([`CONTRIBUTING.md`](../../CONTRIBUTING.md)) From 4683aaf3a7899c7d094720bcba7b5caa59c5ed43 Mon Sep 17 00:00:00 2001 From: russellwheatley Date: Fri, 31 Jul 2026 15:16:45 +0100 Subject: [PATCH 2/3] docs(okf): document CI workflows for agents Map SwiftUI Auth, UIKit module, and sample GitHub Actions jobs to local validation entrypoints and current Xcode/simulator pins. --- okf-bundle/ci-workflows/index.md | 28 +++++++++++++++ okf-bundle/ci-workflows/samples.md | 23 +++++++++++++ okf-bundle/ci-workflows/swiftui-auth.md | 43 ++++++++++++++++++++++++ okf-bundle/ci-workflows/uikit-modules.md | 41 ++++++++++++++++++++++ 4 files changed, 135 insertions(+) create mode 100644 okf-bundle/ci-workflows/index.md create mode 100644 okf-bundle/ci-workflows/samples.md create mode 100644 okf-bundle/ci-workflows/swiftui-auth.md create mode 100644 okf-bundle/ci-workflows/uikit-modules.md diff --git a/okf-bundle/ci-workflows/index.md b/okf-bundle/ci-workflows/index.md new file mode 100644 index 0000000000..463b552e15 --- /dev/null +++ b/okf-bundle/ci-workflows/index.md @@ -0,0 +1,28 @@ +# CI workflows + +GitHub Actions job map for FirebaseUI-iOS. Local command ownership stays in [agent command policy](../testing/agent-command-policy.md) and [running tests](../testing/running-tests.md). + +## Workflows + +| Workflow | Path | Purpose | +|----------|------|---------| +| SwiftUI Auth | [`swiftui-auth.yml`](../../.github/workflows/swiftui-auth.yml) | SwiftFormat check, SPM package unit tests, integration + UI tests with Auth emulator | +| Database | [`database.yml`](../../.github/workflows/database.yml) | CocoaPods `xcodebuild` test, SPM scheme build, `pod lib lint` | +| Firestore | [`firestore.yml`](../../.github/workflows/firestore.yml) | Same shape as Database for Firestore UI | +| Storage | [`storage.yml`](../../.github/workflows/storage.yml) | Same shape as Database for Storage UI | +| Samples | [`sample.yml`](../../.github/workflows/sample.yml) | Build SwiftUI + UIKit sample apps | +| Issue labels / stale | [`issue-labels.yml`](../../.github/workflows/issue-labels.yml), [`stale-issue.yml`](../../.github/workflows/stale-issue.yml) | Repo hygiene (not product validation) | + +## Detail docs + +* [SwiftUI Auth CI](swiftui-auth.md) — jobs, Xcode pin, emulator, artifacts +* [UIKit modules CI](uikit-modules.md) — Database / Firestore / Storage job matrix +* [Samples CI](samples.md) — sample build destinations + +## Shared pins (as of authoring) + +* **Xcode 26.2** selected in module/sample/SwiftUI workflows +* **Simulator:** `iPhone 17 Pro` for most test jobs; SwiftUI sample build uses `iPhone 17` +* **Simulator prep script:** [`.github/workflows/scripts/prepare-ios-simulator.sh`](../../.github/workflows/scripts/prepare-ios-simulator.sh) + +When pins drift, update these OKF docs in the same change that updates CI — do not leave agents on stale device/Xcode names. diff --git a/okf-bundle/ci-workflows/samples.md b/okf-bundle/ci-workflows/samples.md new file mode 100644 index 0000000000..64b9868abf --- /dev/null +++ b/okf-bundle/ci-workflows/samples.md @@ -0,0 +1,23 @@ +--- +type: Reference +title: Samples CI +description: Job shape for .github/workflows/sample.yml. +tags: [ci, samples] +timestamp: 2026-07-31T00:00:00Z +--- + +# Samples CI + +Workflow: [`.github/workflows/sample.yml`](../../.github/workflows/sample.yml). + +## Jobs + +| Job | Area | Notes | +|-----|------|-------| +| `swiftui` | `samples/swiftui/FirebaseSwiftUISample` | `xcodebuild` **build**; destination `iPhone 17` | +| `swift` | `samples/swift` (`FirebaseUI-demo-swift`) | CocoaPods install then `xcodebuild` **`clean build test`**; destination `iPhone 17 Pro` | +| `objc` | `samples/objc` (`FirebaseUI-demo-objc`) | CocoaPods install then `xcodebuild` **`clean build`**; destination `iPhone 17 Pro` | + +Copy **exact** `xcodebuild` / `pod` steps from the workflow when validating sample changes locally — [running tests § samples](../testing/running-tests.md#sample-builds). + +Samples are CI smoke checks for the demo apps (the Swift UIKit sample also runs its test target). They are not a substitute for `./swiftui-tests.sh` or `./test.sh`. diff --git a/okf-bundle/ci-workflows/swiftui-auth.md b/okf-bundle/ci-workflows/swiftui-auth.md new file mode 100644 index 0000000000..1685c6c0bc --- /dev/null +++ b/okf-bundle/ci-workflows/swiftui-auth.md @@ -0,0 +1,43 @@ +--- +type: Reference +title: SwiftUI Auth CI +description: Job shape and triage notes for .github/workflows/swiftui-auth.yml. +tags: [ci, swiftui, auth, emulator] +timestamp: 2026-07-31T00:00:00Z +--- + +# SwiftUI Auth CI + +Workflow: [`.github/workflows/swiftui-auth.yml`](../../.github/workflows/swiftui-auth.yml). + +Local mirror: [`./swiftui-tests.sh`](../../swiftui-tests.sh) — [running tests](../testing/running-tests.md#swiftui-auth-tests). Emulator defaults: [firebase testing project](../testing/firebase-testing-project.md). + +## Jobs + +| Job | What | Notes | +|-----|------|-------| +| `format-check` | `brew install swiftformat` + `./lint-swift.sh` | Paths in `lint-swift.sh` | +| `unit-tests` | `xcodebuild test -scheme FirebaseUI-Package` on prepared simulator | Coverage on; uploads log/xcresult on failure | +| `integration-tests` | Auth emulator + `FirebaseSwiftUIExampleTests` | Node 20, Java 17, `firebase-tools`; `parallel-testing-enabled NO` | +| `ui-tests` | Auth emulator + `build-for-testing` / `test-without-building` for `FirebaseSwiftUIExampleUITests` | Same emulator setup; uploads emulator debug log on failure | + +## Environment + +| Variable / pin | Value | +|----------------|-------| +| `XCODE_VERSION` | `26.2` | +| `IOS_SIMULATOR_DEVICE` | `iPhone 17 Pro` | +| Runner | `macos-26` | +| Emulator project (script default) | `flutterfire-e2e-tests` | +| Emulator port probe | `http://localhost:9099` | + +## Path filters + +PRs/pushes run when `FirebaseSwiftUI/**`, `samples/swiftui/**`, `e2eTest/**`, `Package.swift`, `Package.resolved`, Gemfile, or this workflow change. + +## Triage + +1. Prefer downloading failure artifacts (logs / `.xcresult` / `firebase-debug.log`) over re-running blind. +2. Format failures → `./format-swift.sh` then `./lint-swift.sh`. +3. Emulator failures → confirm Firebase CLI, port `9099`, and project id; locally use `./swiftui-tests.sh --integration`. +4. Simulator resolution failures → inspect `prepare-ios-simulator.sh` output and `xcrun simctl list devices available`. diff --git a/okf-bundle/ci-workflows/uikit-modules.md b/okf-bundle/ci-workflows/uikit-modules.md new file mode 100644 index 0000000000..e36317b8d9 --- /dev/null +++ b/okf-bundle/ci-workflows/uikit-modules.md @@ -0,0 +1,41 @@ +--- +type: Reference +title: UIKit modules CI +description: Job shape for Database, Firestore, and Storage UI GitHub Actions workflows. +tags: [ci, database, firestore, storage, cocoapods, spm] +timestamp: 2026-07-31T00:00:00Z +--- + +# UIKit modules CI + +Workflows (same job shape): + +* [`.github/workflows/database.yml`](../../.github/workflows/database.yml) +* [`.github/workflows/firestore.yml`](../../.github/workflows/firestore.yml) +* [`.github/workflows/storage.yml`](../../.github/workflows/storage.yml) + +Local mirror for the CocoaPods test job: [`./test.sh `](../../test.sh) after `bundle exec pod install` in the module directory — [running tests](../testing/running-tests.md#uikit-module-tests). + +## Jobs (per module) + +| Job | What | +|-----|------| +| `xcodebuild` | In module dir: Bundler + `pod install --repo-update`, then repo-root `./test.sh ` | +| `spm` | Repo-root `xcodebuild -scheme -sdk iphonesimulator` with CI destination | +| `pod` | `bundle exec pod lib lint .podspec` | + +## Environment + +| Pin | Value | +|-----|-------| +| Runner | `macos-15` | +| Xcode | `/Applications/Xcode_26.2.app` via `xcode-select` | +| Destination (spm / test.sh) | `iPhone 17 Pro` (see scripts/workflows for exact string) | + +## Path filters + +Each workflow watches its `FirebaseUI/**`, podspec, `test.sh`, `Package.swift` / `Package.resolved`, Gemfile, and its workflow file. + +## Dual-path reminder + +A green `xcodebuild` CocoaPods job does **not** prove the SPM product compiles (and vice versa). Agents must satisfy the [distribution path gate](../testing/running-tests.md#distribution-path-gate-blocking) when shared sources change. From f686a374535a0558bd0b7d10e5ca634bacc66a34 Mon Sep 17 00:00:00 2001 From: russellwheatley Date: Fri, 31 Jul 2026 15:16:45 +0100 Subject: [PATCH 3/3] docs(okf): add packaging and package module notes Capture SPM vs CocoaPods dual distribution (workflow + work queue) and per-package agent notes for Auth SwiftUI, Database, Firestore, and Storage UI. --- okf-bundle/packages/auth-swiftui/index.md | 46 ++++++++++++++ okf-bundle/packages/database-ui/index.md | 41 +++++++++++++ okf-bundle/packages/firestore-ui/index.md | 38 ++++++++++++ okf-bundle/packages/index.md | 10 ++++ okf-bundle/packages/storage-ui/index.md | 42 +++++++++++++ okf-bundle/packaging/index.md | 4 ++ .../packaging/spm-and-cocoapods-workflow.md | 60 +++++++++++++++++++ .../packaging/spm-cocoapods-work-queue.md | 30 ++++++++++ 8 files changed, 271 insertions(+) create mode 100644 okf-bundle/packages/auth-swiftui/index.md create mode 100644 okf-bundle/packages/database-ui/index.md create mode 100644 okf-bundle/packages/firestore-ui/index.md create mode 100644 okf-bundle/packages/index.md create mode 100644 okf-bundle/packages/storage-ui/index.md create mode 100644 okf-bundle/packaging/index.md create mode 100644 okf-bundle/packaging/spm-and-cocoapods-workflow.md create mode 100644 okf-bundle/packaging/spm-cocoapods-work-queue.md diff --git a/okf-bundle/packages/auth-swiftui/index.md b/okf-bundle/packages/auth-swiftui/index.md new file mode 100644 index 0000000000..10a3d6ee53 --- /dev/null +++ b/okf-bundle/packages/auth-swiftui/index.md @@ -0,0 +1,46 @@ +--- +type: Reference +title: FirebaseAuthSwiftUI package notes +description: Agent reference for SwiftUI Auth core and provider packages. +tags: [auth, swiftui, spm] +timestamp: 2026-07-31T00:00:00Z +--- + +# Auth SwiftUI + +SPM products: `FirebaseAuthSwiftUI`, `FirebaseAuthUIComponents`, `FirebaseGoogleSwiftUI`, `FirebaseFacebookSwiftUI`, `FirebasePhoneAuthSwiftUI`, `FirebaseAppleSwiftUI`, `FirebaseTwitterSwiftUI`, `FirebaseOAuthSwiftUI`. + +## Layout + +| Path | Role | +|------|------| +| `FirebaseSwiftUI/FirebaseAuthSwiftUI/` | Core Auth UI (`AuthService`, flows, strings); package unit tests under `Tests/` | +| `FirebaseSwiftUI/FirebaseAuthUIComponents/` | Shared UI components/resources | +| `FirebaseSwiftUI/Firebase*SwiftUI/` | Provider packages + their `Tests/` | +| `e2eTest/FirebaseSwiftUIExample/` | Integration + UI test host app | +| `samples/swiftui/FirebaseSwiftUISample/` | Manual/sample app | +| `GETTING_STARTED.md` / `FirebaseSwiftUI/README.md` | User-facing docs | + +## Validation + +| Intent | Command | +|--------|---------| +| Lint | `./lint-swift.sh` | +| Package unit | `./swiftui-tests.sh --unit` | +| Integration / UI | `./swiftui-tests.sh --integration` / `--ui` | +| Area / pre-merge | `./swiftui-tests.sh --lint --all` | + +Allowlist: [agent command policy](../../testing/agent-command-policy.md). Detail: [running tests](../../testing/running-tests.md#swiftui-auth-tests). Emulator project: [firebase testing project](../../testing/firebase-testing-project.md). CI: [swiftui-auth CI](../../ci-workflows/swiftui-auth.md). + +## Agent notes + +* Swift 6 language mode is set on these targets in `Package.swift` — treat concurrency/isolation errors as product issues. +* Provider packages depend on `FirebaseAuthSwiftUI` + `FirebaseAuthUIComponents`; keep public Auth configuration APIs stable unless versioning intentionally. +* Version stamp for Swift releases: `FirebaseSwiftUI/FirebaseAuthSwiftUI/Sources/Version.swift` via [`release-swift.sh`](../../../release-swift.sh) (human release process). +* Feature parity with FirebaseUI-Android Auth UI where applicable ([`CONTRIBUTING.md`](../../../CONTRIBUTING.md)). +* Emulator-backed tests use project `flutterfire-e2e-tests` by default. + +## Related + +* [SPM and CocoaPods workflow](../../packaging/spm-and-cocoapods-workflow.md) — Auth is SPM-only for consumers +* [`.agents/skills/firebaseui-ios-getting-started/SKILL.md`](../../../.agents/skills/firebaseui-ios-getting-started/SKILL.md) — getting-started skill (user docs adjacent) diff --git a/okf-bundle/packages/database-ui/index.md b/okf-bundle/packages/database-ui/index.md new file mode 100644 index 0000000000..3793597205 --- /dev/null +++ b/okf-bundle/packages/database-ui/index.md @@ -0,0 +1,41 @@ +--- +type: Reference +title: FirebaseDatabaseUI package notes +description: Agent reference for Realtime Database UIKit bindings. +tags: [database, uikit, cocoapods, spm] +timestamp: 2026-07-31T00:00:00Z +--- + +# Database UI + +CocoaPods: `FirebaseDatabaseUI` / `FirebaseUI/Database`. SPM product: `FirebaseDatabaseUI`. + +## Layout + +| Path | Role | +|------|------| +| `FirebaseDatabaseUI/Sources/` | ObjC implementation + public headers | +| `FirebaseDatabaseUI/FirebaseDatabaseUITests/` | XCTest (array/data source behavior) | +| `FirebaseDatabaseUI/Podfile` | Local workspace deps (`Firebase/Database`) | +| `FirebaseDatabaseUI.podspec` | CocoaPods publish metadata | +| `FirebaseDatabaseUI/README.md` | User-facing API overview | + +Key types: `FUIArray`, `FUISortedArray`, `FUIIndexArray`, `FUITableViewDataSource`, `FUICollectionViewDataSource`, index variants — see module README. + +## Validation + +```bash +cd FirebaseDatabaseUI && bundle exec pod install && cd .. +./test.sh FirebaseDatabaseUI +xcodebuild -scheme FirebaseDatabaseUI -sdk iphonesimulator \ + -destination 'platform=iOS Simulator,OS=latest,name=iPhone 17 Pro' +bundle exec pod lib lint FirebaseDatabaseUI.podspec # when podspec/packaging changes +``` + +CI: [uikit-modules CI](../../ci-workflows/uikit-modules.md). Distribution: [SPM and CocoaPods workflow](../../packaging/spm-and-cocoapods-workflow.md). + +## Agent notes + +* Array/data-source updates are concurrency-sensitive (batch updates vs Firebase child events). Prefer regression tests in `FirebaseDatabaseUITests` when touching `FUIArray` / collection data sources. +* Keep SPM header search paths / `publicHeadersPath` intact when moving headers (`Package.swift` target settings). +* Do not "fix" desyncs by skipping UI updates without tests — recent history includes desync crash fixes that require lockstep item/UI updates. diff --git a/okf-bundle/packages/firestore-ui/index.md b/okf-bundle/packages/firestore-ui/index.md new file mode 100644 index 0000000000..7f0a5f7859 --- /dev/null +++ b/okf-bundle/packages/firestore-ui/index.md @@ -0,0 +1,38 @@ +--- +type: Reference +title: FirebaseFirestoreUI package notes +description: Agent reference for Firestore UIKit bindings. +tags: [firestore, uikit, cocoapods, spm] +timestamp: 2026-07-31T00:00:00Z +--- + +# Firestore UI + +CocoaPods: `FirebaseFirestoreUI` / `FirebaseUI/Firestore`. SPM product: `FirebaseFirestoreUI`. + +## Layout + +| Path | Role | +|------|------| +| `FirebaseFirestoreUI/Sources/` | ObjC implementation + public headers | +| `FirebaseFirestoreUI/FirebaseFirestoreUITests/` | XCTest | +| `FirebaseFirestoreUI/Podfile` | Local workspace deps | +| `FirebaseFirestoreUI.podspec` | CocoaPods publish metadata | +| `FirebaseFirestoreUI/README.md` | User-facing API overview | + +## Validation + +```bash +cd FirebaseFirestoreUI && bundle exec pod install && cd .. +./test.sh FirebaseFirestoreUI +xcodebuild -scheme FirebaseFirestoreUI -sdk iphonesimulator \ + -destination 'platform=iOS Simulator,OS=latest,name=iPhone 17 Pro' +bundle exec pod lib lint FirebaseFirestoreUI.podspec # when podspec/packaging changes +``` + +CI: [uikit-modules CI](../../ci-workflows/uikit-modules.md). Distribution: [SPM and CocoaPods workflow](../../packaging/spm-and-cocoapods-workflow.md). + +## Agent notes + +* Same dual-distribution rules as Database UI — CocoaPods test path + SPM scheme when shared sources change. +* Preserve public header layout for both podspec `source_files` / header maps and SPM `publicHeadersPath`. diff --git a/okf-bundle/packages/index.md b/okf-bundle/packages/index.md new file mode 100644 index 0000000000..43ea27bf40 --- /dev/null +++ b/okf-bundle/packages/index.md @@ -0,0 +1,10 @@ +# Packages + +Durable, topic-owned notes for FirebaseUI-iOS libraries (RNFB-equivalent of `okf-bundle/packages/`). User-facing guides remain in module READMEs / `GETTING_STARTED.md`; OKF pages capture **agent** constraints, test entrypoints, and sharp edges. + +| Package | Doc | Tree | +|---------|-----|------| +| Auth SwiftUI (+ providers) | [auth-swiftui](auth-swiftui/index.md) | `FirebaseSwiftUI/**` | +| Database UI | [database-ui](database-ui/index.md) | `FirebaseDatabaseUI/**` | +| Firestore UI | [firestore-ui](firestore-ui/index.md) | `FirebaseFirestoreUI/**` | +| Storage UI | [storage-ui](storage-ui/index.md) | `FirebaseStorageUI/**` | diff --git a/okf-bundle/packages/storage-ui/index.md b/okf-bundle/packages/storage-ui/index.md new file mode 100644 index 0000000000..58c2b48324 --- /dev/null +++ b/okf-bundle/packages/storage-ui/index.md @@ -0,0 +1,42 @@ +--- +type: Reference +title: FirebaseStorageUI package notes +description: Agent reference for Storage UIKit bindings and Swift bridge. +tags: [storage, uikit, cocoapods, spm, sdwebimage] +timestamp: 2026-07-31T00:00:00Z +--- + +# Storage UI + +CocoaPods: `FirebaseStorageUI` / `FirebaseUI/Storage`. SPM products: `FirebaseStorageUI`, `FirebaseStorageUISwift`. + +## Layout + +| Path | Role | +|------|------| +| `FirebaseStorageUI/Sources/` | ObjC UIImageView categories, Storage download integration, SDWebImage hooks | +| `FirebaseStorageUI/SwiftBridge/` | Sources for the `FirebaseStorageUISwift` SPM product | +| `FirebaseStorageUI/FirebaseStorageUITests/` | XCTest | +| `FirebaseStorageUI/Podfile` | Local workspace deps | +| `FirebaseStorageUI.podspec` | CocoaPods publish metadata | +| `FirebaseStorageUI/README.md` | User-facing API overview | + +Depends on Firebase Storage + **SDWebImage** (see `Package.swift` / podspec). + +## Validation + +```bash +cd FirebaseStorageUI && bundle exec pod install && cd .. +./test.sh FirebaseStorageUI +xcodebuild -scheme FirebaseStorageUI -sdk iphonesimulator \ + -destination 'platform=iOS Simulator,OS=latest,name=iPhone 17 Pro' +bundle exec pod lib lint FirebaseStorageUI.podspec # when podspec/packaging changes +``` + +CI: [uikit-modules CI](../../ci-workflows/uikit-modules.md). Distribution: [SPM and CocoaPods workflow](../../packaging/spm-and-cocoapods-workflow.md). + +## Agent notes + +* `FirebaseStorageUISwift` is a published SPM **product** (not an internal-only target) — update the Swift bridge when changing the public Swift surface for SPM consumers. +* SDWebImage integration and `FIRStorageDownloadTask` categories are load-bearing; add tests under `FirebaseStorageUITests` when changing download/image loader behavior. +* Dual-distribution gate applies to `Sources/` the same as Database/Firestore. diff --git a/okf-bundle/packaging/index.md b/okf-bundle/packaging/index.md new file mode 100644 index 0000000000..170914ed02 --- /dev/null +++ b/okf-bundle/packaging/index.md @@ -0,0 +1,4 @@ +# Packaging + +* [SPM and CocoaPods workflow](spm-and-cocoapods-workflow.md) — dual distribution rules, product matrix, release entrypoints +* [SPM / CocoaPods work queue](spm-cocoapods-work-queue.md) — ephemeral tracker for distribution gaps diff --git a/okf-bundle/packaging/spm-and-cocoapods-workflow.md b/okf-bundle/packaging/spm-and-cocoapods-workflow.md new file mode 100644 index 0000000000..6db499fb18 --- /dev/null +++ b/okf-bundle/packaging/spm-and-cocoapods-workflow.md @@ -0,0 +1,60 @@ +--- +type: Reference +title: SPM and CocoaPods dual distribution workflow +description: Durable rules for Swift Package Manager vs CocoaPods products, source ownership, and release scripts. +tags: [spm, cocoapods, packaging, distribution, workflow] +timestamp: 2026-07-31T00:00:00Z +--- + +# SPM and CocoaPods dual distribution workflow + +FirebaseUI-iOS ships **two consumer distribution channels** with different product sets. Agents must not assume "one install story" for the whole monorepo. + +Ephemeral tracking: [SPM / CocoaPods work queue](spm-cocoapods-work-queue.md). Policy for queues: [documentation policy](../documentation-policy.md). + +## Product matrix + +| Product | Consumer path | Sources | Min iOS (approx.) | +|---------|---------------|---------|-------------------| +| `FirebaseAuthSwiftUI` + provider libs (`FirebaseGoogleSwiftUI`, `FirebaseFacebookSwiftUI`, `FirebasePhoneAuthSwiftUI`, `FirebaseAppleSwiftUI`, `FirebaseTwitterSwiftUI`, `FirebaseOAuthSwiftUI`) | **SPM only** (`Package.swift`) | `FirebaseSwiftUI/**` | iOS 17+ (package platforms) | +| `FirebaseAuthUIComponents` | SPM product (shared UI components for Auth) | `FirebaseSwiftUI/FirebaseAuthUIComponents` | iOS 17+ | +| `FirebaseDatabaseUI` | CocoaPods (`FirebaseDatabaseUI.podspec` / `FirebaseUI/Database`) **and** SPM product | `FirebaseDatabaseUI/Sources` | Pods historically iOS 13+; SPM package platforms iOS 17+ | +| `FirebaseFirestoreUI` | CocoaPods + SPM product | `FirebaseFirestoreUI/Sources` | same dual note | +| `FirebaseStorageUI` | CocoaPods + SPM product | `FirebaseStorageUI/Sources` | same dual note | +| `FirebaseStorageUISwift` | **SPM product** (Swift bridge; depends on `FirebaseStorageUI`) | `FirebaseStorageUI/SwiftBridge` | iOS 17+ (package platforms) | +| Umbrella `FirebaseUI` pod | CocoaPods only (`FirebaseUI.podspec` subspecs) | header umbrella + subspec deps | see podspec | + +Canonical consumer docs: [`README.md`](../../README.md), [`GETTING_STARTED.md`](../../GETTING_STARTED.md), [`FirebaseSwiftUI/README.md`](../../FirebaseSwiftUI/README.md). + +## Rules + +1. **SwiftUI Auth is SPM-first.** Do not add CocoaPods subspecs for `FirebaseAuthSwiftUI` / provider packages unless durable docs and CI are updated in the same change. +2. **UIKit data-binding modules are dual-built.** Edits under `Firebase*UI/Sources` must keep CocoaPods tests and SPM scheme builds green ([distribution path gate](../testing/running-tests.md#distribution-path-gate-blocking)). +3. **One source tree per module.** Do not fork SPM-only copies of UIKit sources; `Package.swift` targets point at the same `Sources` directories as the pods. +4. **Versioning is split operationally:** + - CocoaPods / umbrella: [`release.sh`](../../release.sh), [`staging.sh`](../../staging.sh), podspecs + - SwiftUI Auth package version stamp: [`release-swift.sh`](../../release-swift.sh) updates `FirebaseSwiftUI/FirebaseAuthSwiftUI/Sources/Version.swift` (human-driven; agents need explicit user request) +5. **Swift language mode:** SwiftUI Auth targets set `.swiftLanguageMode(.v6)` in `Package.swift`. Do not silently relax to silence concurrency errors — fix or record an accepted exception. + +## `Package.swift` ownership + +- Tools version / package name: `FirebaseUI` +- Platforms: `.iOS(.v17)` +- UIKit SPM targets use ObjC `publicHeadersPath` + header search paths — preserve these when moving files +- Storage exposes both `FirebaseStorageUI` (ObjC product) and `FirebaseStorageUISwift` (Swift bridge **product**) + +## CocoaPods ownership + +- Per-module podspecs at repo root: `FirebaseDatabaseUI.podspec`, `FirebaseFirestoreUI.podspec`, `FirebaseStorageUI.podspec`, umbrella `FirebaseUI.podspec` +- Module `Podfile`s under each `Firebase*UI/` directory drive local test workspaces +- Prefer `bundle exec` with repo [`Gemfile`](../../Gemfile) + +## Decision log (durable) + +| ID | Decision | Status | +|----|----------|--------| +| Dist-AD-1 | SwiftUI Auth ships via SPM; UIKit Database/Firestore/Storage remain CocoaPods-supported and SPM-listed | Accepted | +| Dist-AD-2 | Shared UIKit sources must pass both CocoaPods `./test.sh` and CI SPM scheme jobs when changed | Accepted | +| Dist-AD-3 | Agents do not run trunk/release scripts without explicit user request | Accepted | + +New distribution decisions get a row here; active migration tasks go in the [work queue](spm-cocoapods-work-queue.md). diff --git a/okf-bundle/packaging/spm-cocoapods-work-queue.md b/okf-bundle/packaging/spm-cocoapods-work-queue.md new file mode 100644 index 0000000000..197b5b71de --- /dev/null +++ b/okf-bundle/packaging/spm-cocoapods-work-queue.md @@ -0,0 +1,30 @@ +--- +type: Reference +title: SPM / CocoaPods distribution work queue +description: Phase tracker for dual-distribution gaps and packaging follow-ups. +tags: [spm, cocoapods, work-queue, ephemeral] +timestamp: 2026-07-31T00:00:00Z +--- + +# SPM / CocoaPods work queue + +Ephemeral. Field ids: [iteration vocabulary](../testing/iteration-vocabulary.md). Durable rules: [SPM and CocoaPods workflow](spm-and-cocoapods-workflow.md). Commit/doc policy: [documentation policy](../documentation-policy.md). + +Do not copy policy into this file — link only. + +## Active items + +| id | item | next_work_type | validation_tier | implementation_gate | review_gate | commit_gate | commit_subject | notes | +|----|------|----------------|-----------------|----------------------|-------------|-------------|----------------|-------| +| DIST-1 | Keep OKF dual-distribution docs aligned when CI Xcode/simulator pins or podspec/SPM matrix change | `documentation` | none | open | open | open | | Standing maintenance item; reopen whenever CI pins or product matrix drift | +| DIST-2 | Clarify / close any remaining consumer messaging gaps between README SPM-vs-CocoaPods guidance and Package.swift product list | `gap-analysis` | none | open | open | open | | Durable outcome → [spm-and-cocoapods-workflow.md](spm-and-cocoapods-workflow.md) Decision log | + +## Parked / blocked + +| id | item | blocked | notes | +|----|------|---------|-------| +| — | — | — | — | + +## Archive + +_None yet._