mirror of
https://github.com/facebook/react-native.git
synced 2026-11-18 20:19:07 +00:00
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:
1 parent
b95c5db26b
commit
a6898cc4cf
9 files changed
+918
-1550
No files matched your search
@@ -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
|
||||
|
||||
Reference in new issue
Block a user