diff --git a/docsite/docs/contributing/versioning.md b/docsite/docs/contributing/versioning.md index ccb792f581e3..d7c9a2916e38 100644 --- a/docsite/docs/contributing/versioning.md +++ b/docsite/docs/contributing/versioning.md @@ -5,12 +5,41 @@ sidebar_position: 3 # Versioning -React Native macOS uses [NX Release](https://nx.dev/features/manage-releases) to control its versioning. Our minor releases are synced to upstream releases of React Native, but our patch versions may differ. For instance, `react-native-macos@0.78.5` corresponds to `react-native@0.78.2`. You can find out how we sync our releases by looking at our packages' [react-native peer dependency](https://github.com/microsoft/react-native-macos/blob/8f8fd013d2a36cf2635dbcef76970119f7672b51/packages/react-native/package.json#L105). +React Native macOS uses [Changesets](https://github.com/changesets/changesets) to record release intent. +React Native macOS package versions are managed independently from upstream React Native versions, so their +patch numbers do not have to match. For example, `react-native-macos@0.78.5` can correspond to +`react-native@0.78.2`. On stable branches, the `react-native` peer dependency in +[`packages/react-native/package.json`](https://github.com/microsoft/react-native-macos/blob/main/packages/react-native/package.json) +is the source of truth for that correspondence. -## How to push a new patch release +## Add release intent to a pull request -If you have a PR you'd like to be included in a new release, you can add a [version plan](https://nx.dev/recipes/nx-release/file-based-versioning-version-plans#file-based-versioning-version-plans) to it. +For a normal pull request that changes a public package, run: ```shell -yarn nx release plan --message 'fix some bug' --only-touched=false patch -``` \ No newline at end of file +yarn change +``` + +Select the affected packages, choose the appropriate bump, and write a concise user-facing summary. This creates a +file under `.changeset/` that should be committed with the pull request. Run `yarn change:check` to perform the same +validation used by CI: every changed public package must have release intent, and major bumps are rejected. You can +also inspect the calculated releases directly with `yarn changeset status --since `. + +If a pull request changes package files but should not produce a release, add an empty Changeset instead: + +```shell +yarn changeset --empty +``` + +The repository's [`yarn change` and `yarn change:check` scripts](https://github.com/microsoft/react-native-macos/blob/main/.github/scripts/change.mts) +select the appropriate repository remote and validate Changesets. CI requires this validation for pull requests into +active `*-stable` branches. + +## Materialize a release + +Pushing Changesets to an active `*-stable` branch triggers the +[Changesets version workflow](https://github.com/microsoft/react-native-macos/blob/main/.github/workflows/microsoft-changesets-version.yml). +The Changesets action creates or updates a follow-up version-bump pull request. That pull request runs +`yarn changeset:version`, which consumes the pending Changesets, updates package versions and changelogs, updates +native version artifacts, and refreshes the lockfile. Version and changelog edits therefore belong in that generated +version pull request, not in the original feature or stable-sync pull request. diff --git a/docsite/docs/releases/patch-release.md b/docsite/docs/releases/patch-release.md index 292c1508cfac..96afd17211e4 100644 --- a/docsite/docs/releases/patch-release.md +++ b/docsite/docs/releases/patch-release.md @@ -3,20 +3,75 @@ sidebar_label: 'Sync to a new patch release' sidebar_position: 2 --- -# Sync to a new upstream React Native patch release +# Sync to a new upstream React Native patch release -Let's assume that we are trying to release a new patch release of `0.76.x`. Let's also assume that the latest commit in React Native's `0.76-stable` branch is the release commit we want to sync to. If not, `git merge` to an earlier commit. +This process brings a specific upstream React Native stable release into the matching React Native macOS stable +branch. Always identify and review the exact upstream release commit first. Merge its full SHA rather than the moving +tip of the upstream stable branch so the pull request cannot silently change while it is being prepared. +The example below uses `0.83-stable`; substitute the minor version and release SHA you are syncing: -Roughly, run the following commands to: -- Sync to the latest commit in React Native's 0.76-stable branch. -- Merge that branch into yours -- Add a version plan +```shell +RN_MINOR=0.83 +RN_RELEASE_SHA= + +git fetch upstream "$RN_MINOR-stable" +git switch "$RN_MINOR-stable" +git merge --ff-only "upstream/$RN_MINOR-stable" +git switch -c "$RN_MINOR/sync-upstream-patch" + +git fetch facebook "$RN_MINOR-stable" +git merge "$RN_RELEASE_SHA" +``` + +This branches from the matching, updated local React Native macOS stable branch and merges only the pinned React +Native commit. + +## Record the sync + +After resolving the upstream merge: + +1. Update the `react-native` peer dependency in + [`packages/react-native/package.json`](https://github.com/microsoft/react-native-macos/blob/main/packages/react-native/package.json) + to the actual upstream React Native version represented by `RN_RELEASE_SHA`. +2. Run `yarn change`, select all public packages affected by the sync, and describe the upstream version being merged. + Alternatively, create an explicitly named `.changeset/*.md` file with package frontmatter and the same + user-facing summary. +3. Choose each package's bump based on its current version and the intended release. A later release in an existing + minor line normally uses a patch bump. The first release of a new minor line may require a minor or prerelease + transition from the package's seed/current version; do not select patch automatically. + +For example, an explicitly authored Changeset for one package has this shape: + +```markdown +--- +'react-native-macos': patch +--- + +Sync to upstream React Native 0.83.x. +``` + +## Regenerate and validate + +Regenerate dependency state and RNTester pods after the peer and merged sources change: ```shell -git switch -c 0.76/release upstream/0.76-stable -git merge facebook/0.76-stable -yarn nx release plan --message 'Sync to upstream React Native 0.76.x release' --only-touched=false patch +yarn install +(cd packages/rn-tester && bundle exec pod install) ``` -Remember to update the peer dependency in `packages/react-native` for React Native macOS to the version you have merged to. +Validate against the stable branch rather than `main`: + +```shell +GITHUB_BASE_REF=0.83-stable yarn change:check +yarn changeset status --since upstream/0.83-stable +``` + +Commit the resulting Changeset, `yarn.lock`, and `packages/rn-tester/Podfile.lock` updates with the sync. CI runs +`yarn change:check` for pull requests targeting `*-stable`. + +Once the sync pull request lands on the stable branch, the +[Changesets version workflow](https://github.com/microsoft/react-native-macos/blob/main/.github/workflows/microsoft-changesets-version.yml) +creates or updates a follow-up version-bump pull request. That pull request runs `yarn changeset:version` to consume +the Changeset and materialize package version and changelog updates. Do not manually add those generated edits to the +sync pull request.