docs(swiftpm): rename __doc__ to __docs__, drop two superseded docs, correct the rest (#58006)

Summary:
Rebased onto `main` after https://github.com/react/react-native/issues/57757, https://github.com/react/react-native/issues/57756, https://github.com/react/react-native/issues/57762 and https://github.com/react/react-native/issues/57744 landed. Because this
PR renames `__doc__` and Prettier-formats every file, a hunk-level rebase was the
wrong tool — it stopped on the second of nine commits and the reformat commit then
conflicted with everything after it. So the history is **replayed** on top of the
new `main` instead, and reordered to put Prettier *before* the content edits, which
makes the substantive diff reviewable rather than tangled with reflow.

Verified nothing those four PRs added was lost: every heading on `main` survives
except the two this PR deliberately renames, and their facts — the
`artifactsVersionOverride` pin, the autolinking-config-command pin, the
pre-injection build-setting values, and the promoted-scalar caveat — are carried
into the new "Files the tool touches" table rather than sitting in a row this PR
deletes.

Housekeeping and accuracy pass over `packages/react-native/scripts/spm/__docs__`.
Docs only — no code or test changes.

**Rename.** `scripts/spm/__doc__` was the only `__doc__` directory in the repo;
every other subsystem uses `__docs__` (27+ directories, and the convention
documented in `__docs__/GUIDELINES.md`). The misspelling also meant these files
were **published to npm**: `package.json` includes `scripts/spm` in `files` and
excludes `!**/__docs__/**`, which the misspelled directory dodged.

**Removed two superseded documents.** `rfc-spm-xcframework.md` (707 lines) was a
stale ancestor of RFC0994, still describing `spm init`, xcodeproj *generation*, the
`.xcodeproj.legacy` rename migration, a `spm clean` command that does not exist,
stub `Package.swift` files and VFS overlays. `spm-plugins-assessment.md` evaluated
SwiftPM plugins as a replacement for the injected build phases — conclusion valid,
detail stale (it listed a "Prepare VFS Overlay" phase). Both have had their durable
content folded into RFC0994.

**Corrected the remaining docs against the implementation.** The substantive one:
auto-sync is **two** hooks, not one — a scheme pre-action in the app's *shared*
scheme plus the build phase. The docs described only the phase.

Two claims here are corrections of my own earlier drafts, made after testing them
on `private/helloworld` rather than reading the code:

- Neither hook can bootstrap a clean checkout. With `build/` deleted,
  `xcodebuild -scheme … build` fails in nine lines of log, `Resolve Package Graph`
  first, the pre-action never running. The one-time setup run really is required,
  and the ordering table now shows the measured sequence.
- A sync failure is not unconditionally non-fatal. Exit 2 — a dependency with no
  `Package.swift` — maps to `exit 1` and fails the build deliberately; only other
  non-zero codes warn. As written, the doc also contradicted the exit-2 behaviour
  documented elsewhere in the same file.

Smaller fixes: `hermesvm` → `hermes-engine` (that name is in no code), plugin
`watchPaths` added to the staleness inputs, and the `#auto-sync-build-phase`
anchors left dangling by the heading rename.

**Added a `__docs__/README.md` index**, per `GUIDELINES.md`, plus a **"Files the
tool touches"** table — there was no single answer to what the tool creates or
modifies. Writing it surfaced that `add` creates or appends to `ios/.gitignore`
(documented nowhere), and that `deinit` does not revert that block, anything
`--deintegrate` changed, or a promoted array setting — so the "exact inverse of
`add`" claim needed qualifying in three places.

**Documented `spm.dependencies`**, the SwiftPM analog of a podspec's
`s.dependency`, which was implemented but absent from every doc, and corrected the
scaffold prerequisite: it is `add`/`update` that stops, with a distinct exit code 2,
not the build.

**Prettier-formatted the docs, in its own commit.** These were the only unformatted
markdown files in the repository, so `prettier --list-different "./**/*.md"` goes
from three failures to clean.

## Changelog:

[Internal] - SwiftPM docs: rename `__doc__` to `__docs__`, remove two superseded
documents, and correct the rest against the implementation

Pull Request resolved: https://github.com/react/react-native/pull/58006

Test Plan:
- `npx prettier --check "packages/react-native/scripts/spm/__docs__/*.md"` passes;
  `npx prettier --list-different "./**/*.md"` is empty for the whole repo.
- All 19 intra-doc anchor links verified against GitHub's slug rules; none dead.
  Every relative path out of the new README resolves, including the root-index hop.
- `npm pack --dry-run --ignore-scripts` lists no `scripts/spm/__docs__/` entries
  while every `scripts/spm/*.js` still ships.
- The Prettier commit is content-neutral: comparing `[A-Za-z0-9]+` token streams
  across it, all three files are identical word for word.
- Behavioural claims traced to source: `VALID_ACTIONS` in `setup-apple-spm.js`;
  `injectOrCreateScheme` / `addPreActionToScheme` and the `RC -eq 2` branch of
  `buildSyncAutolinkingScript` in `generate-spm-xcodeproj.js`; `BUILTIN_FRAMEWORKS`
  in `flavored-frameworks.js`; `generateXCFrameworksPackageSwift` in
  `generate-spm-package.js`; `ensureGitignoreSpmEntries` and its `action =--sanitized--

Reviewed By: fabriziocucci

Differential Revision: D116598871

Pulled By: cipolleschi

fbshipit-source-id: b1822dcc885b9c882ec3a2626addc42553244b51
This commit is contained in:
Christian Falch authored and meta-codesync[bot] committed 2026-08-19 09:19:58 -07:00
1 parent b95c5db26b
commit a6898cc4cf
9 files changed
+918 -1550

No files matched your search

+1
View File
@@ -80,6 +80,7 @@ TODO: Explain the different components of React Native at a high level.
- Build system
- Android
- iOS
- [SwiftPM](../packages/react-native/scripts/spm/__docs__/README.md)
- C++
- JavaScript
- Metro