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
(cherry picked from commit a6898cc4cf)
Summary:
Pull Request resolved: https://github.com/facebook/react-native/pull/50699
Changelog: [internal]
Just changing the template to include emojis in the top level titles to make it easier to scan the doc
Reviewed By: lenaic
Differential Revision: D72961870
fbshipit-source-id: 64c45e7ac769c38af06ea318cdb581a04e230f90
Summary:
Pull Request resolved: https://github.com/facebook/react-native/pull/50665
Changelog: [internal]
Just a stylistic change of the link back to the documentation home.
It also changes the link in the template to make sure it's incorrect so people are forced to edit it when creating new docs.
Reviewed By: lenaic
Differential Revision: D72866823
fbshipit-source-id: fa7be286f996049b3f06e2defa5a8c486d63091b
Summary:
Pull Request resolved: https://github.com/facebook/react-native/pull/50587
Changelog: [internal]
This does an initial formatting of all Markdown files that are going to be formatted by prettier from now on.
Reviewed By: lenaic
Differential Revision: D72706240
fbshipit-source-id: b365a94e5d74945a121966fddcb43776ebc534e0
Summary:
Pull Request resolved: https://github.com/facebook/react-native/pull/50528
Changelog: [internal]
This adds basic documentation for the IntersectionObserver Web API implementation in React Native.
Reviewed By: lenaic
Differential Revision: D72573107
fbshipit-source-id: 14ed318ae3691550bbe14a6da1184013ce0c60a9
Summary:
Pull Request resolved: https://github.com/facebook/react-native/pull/50527
Changelog: [internal]
This just defines an outline for the expected docs to be added to RN.
Reviewed By: GijsWeterings
Differential Revision: D72573497
fbshipit-source-id: a8e1c2cc0c6b966656d1089cd33b547174ace873
Summary:
Pull Request resolved: https://github.com/facebook/react-native/pull/50525
Changelog: [internal]
Just a rename of the file and moving relevant documentation to the README.
Reviewed By: GijsWeterings
Differential Revision: D72562795
fbshipit-source-id: d675037376a0345dd7d178cf5863f4093eb74542
Summary:
Pull Request resolved: https://github.com/facebook/react-native/pull/50335
Changelog: [internal]
This defines the internal technical documentation for the MutationObserver API, as an example of how to define docs using the new strategy and structure.
Reviewed By: javache
Differential Revision: D71890748
fbshipit-source-id: 3ef19c784dff7aea7a2e2d08302640d5eefacc30
Summary:
Pull Request resolved: https://github.com/facebook/react-native/pull/50334
Changelog: [internal]
This updates the documentation for the feature flag system to adhere to the new documentation strategy and structure.
Reviewed By: javache, rshest
Differential Revision: D71889753
fbshipit-source-id: 7ff47cf613ac01012e7329485d2b97e997a97c07
Summary:
Pull Request resolved: https://github.com/facebook/react-native/pull/50333
Changelog: [internal]
This defines a placeholder for the main entrypoint for the React Native internal technical documentation.
Reviewed By: javache, mdvacca, rshest
Differential Revision: D71889755
fbshipit-source-id: 453518a0b7ec2cf433884a87446a7a622418d0b2
Summary:
Pull Request resolved: https://github.com/facebook/react-native/pull/50332
Changelog: [internal]
This defines a detailed strategy on how to approach internal technical documentation in React Native, including defining a template for subsystem documentation.
Reviewed By: javache, rshest
Differential Revision: D71889754
fbshipit-source-id: 5ce630b2e71f8c7b6aaf027a5833bcbdf0dfa5de
Christian Falch