Add step for updating packages in the release guide (#3645)

Author: fortmarek

website/contributing/release-branch-cut-and-rc0.md

@@ -28,18 +28,26 @@ Documents in this section go over steps to run different types of React Native r
   git checkout -b 0.69-stable
   ```
 
+### 2. Update the Hermes version
+
 - Head to the [Publish Tag](https://github.com/facebook/hermes/actions/workflows/create-tag.yml) workflow in the Hermes repo. Click the "Run Workflow" button and input the RN stable version you are targeting (e.g. 0.69.0). You need to have write access to the facebook/hermes repo to do so or ask a Meta employee to help you on this step.
 
 - Bump the Hermes version on the release branch using this command:
 
   ```bash
   # Replace <the_hermes_tag> with the tag that will look like 'hermes-2022-07-20-RNv0.70.0-bc97c5399e0789c0a323f8e1431986e207a9e8ba'
-  ./scripts/hermes/bump-hermes-version.js -t <the_hermes_tag>
+  ./packages/react-native/scripts/hermes/bump-hermes-version.js -t <the_hermes_tag>
   ```
 
-- Add and commit the extra file that got created at `sdks/hermes/.hermesversion`.
+- Add and commit the extra file that got created at `packages/react-native/sdks/hermes/.hermesversion`.
+
+### 3. Bump monorepo packages
+
+- Update packages in the monorepo by running `yarn bump-all-updated-packages`. Bear in mind that all the package bumps must be on patch level, and be on the minor you are working on. We need to publish the latest package changes so they will be included in RC0. Read more about the script and how they work [here](./release-updating-packages).
+
+- CI will take care of releasing the new versions on npm once you push the changes to the `0.XX-stable` branch.
 
-### 2. Push the branch and test the current changes
+### 4. Push the branch and test the current changes
 
 You can now push the branch you created so that others can also start testing:
 
@@ -51,7 +59,7 @@ Before continuing further, follow the [testing guide](/contributing/release-test
 
 <AsyncTestingNote/>
 
-### 3. Kick off the build of 0.{minor}.0-rc.0
+### 5. Kick off the build of 0.{minor}.0-rc.0
 
 Once you're done with the testing, you can kick-off the bump and publishing of RC0:
 
@@ -78,7 +86,9 @@ Once you're done with the testing, you can kick-off the bump and publishing of R
   latest: 0.68.1            next: 0.69.0-rc.0         nightly: 0.0.0-f617e022c
   ```
 
-### 4. Create a PR of the changelog using the generator
+- Hermes artifacts will be uploaded to the [Maven repository](https://repo1.maven.org/maven2/com/facebook/react/react-native-artifacts/). It might take ~20 minutes for Maven to process them.
+
+### 6. Create a PR of the changelog using the generator
 
 To generate the changelog, we rely on a dedicated tool called [`@rnx-kit/rn-changelog-generator`](https://github.com/microsoft/rnx-kit/tree/main/incubator/rn-changelog-generator) that will parse the custom changelog messages that contributors write in their PRs.
 
@@ -109,33 +119,41 @@ For both these categories, we have to manually go through the listed commits and
 - Commit which bumps dependencies should be **moved to the `Changed`** section
   - For each dependency, there should be a single entry with the most recent bump. Commits that bumps the dependencies to lower versions can be **removed**
 
-### 5. Create a GitHub Release
+### 7. Create a GitHub Release
 
 - Create a [GitHub Release](https://github.com/facebook/react-native/releases) with this template and **check "Pre-Release" checkbox**.
 
 <GHReleasesNotesPrerelease />
 
-### 6. Upload prebuilt Hermes binary
+### 8. Upload prebuilt Hermes binary
 
 In the `publish_release` CI workflow, the `build_hermes_macos` step produces a `tmp/hermes/output/hermes-runtime-darwin-vx.y.z.tar.gz` artifact, for example [here](https://app.circleci.com/pipelines/github/facebook/react-native/13933/workflows/5f2ad198-2264-4e7e-8c62-7b28e97532d8/jobs/262322/artifacts) are the artifacts for `0.69.0` release. Download it and attach it to the GitHub release.
 
-### 7. Create a tracking discussion post
+### 9. Create a tracking discussion post
 
 Create a "Road to <YOUR_MINOR_VERSION>" discussion post in the [`react-native-releases`](https://github.com/reactwg/react-native-releases/discussions) working group:
 
 <RoadToReleaseTemplate />
 
 After creating it, make sure to link it in the relevant GitHub Release you created above, and to pin it in the discussion repo.
 
-### 8. Verify that Upgrade Helper GitHub action has fired
+### 10. Verify that Upgrade Helper GitHub action has fired
 
 - You should see a [new publish job here](https://github.com/react-native-community/rn-diff-purge/actions).
 - Once it has finished, you should be able to see that the [Upgrade Helper](https://react-native-community.github.io/upgrade-helper/) presents the option to target the new RC0.
 - If not, check out the guide on [how to update Upgrade Helper](/contributing/updating-upgrade-helper).
 
-### 9. Broadcast that release candidate is out
+### 11. Broadcast that release candidate is out
 
 Once all the steps above have been completed, it's time to signal to the community that RC0 is available for testing! Do so in the following channels:
 
 - [@reactnative](https://twitter.com/reactnative) on twitter
 - RN Discord `#releases-coordination`
+
+### 12. Bump minor version of all monorepo packages in `main`
+
+The packages in the `react-native` monorepo must always be one minor version ahead of the latest or RC version (e.g. if you have cut `0.72-stable`, main needs to be in `0.73.x`. Once you're done with releasing the initial RC0, you should:
+
+- Create a new branch in `react-native` from `main` in your own fork.
+- Run `yarn bump-all-updated-packages --release-branch-cutoff` to bump the minor versions of all packages.
+- Create a PR targeting `main` in `react-native` with the commit created by the previous command.

website/contributing/release-updating-packages.md

@@ -0,0 +1,93 @@
+---
+id: release-updating-packages
+title: Updating monorepo packages
+---
+
+This page contains relevant information about how to update packages in the `react-native` [monorepo](https://github.com/react-native-community/discussions-and-proposals/pull/480).
+
+## Finding all packages that have unpublished changes
+
+#### Use case
+
+1. You want to identify each package with unpublished (on npm) changes and update its version. This can be used in release cycle if you have merged some fixes to `*-stable` branch.
+2. You want to force-bump each public package to the next minor version. This happens usually before release branch cutoff. In this case, please specify `release-branch-cutoff` argument before executing the script.
+
+#### How to execute
+
+`yarn bump-all-updated-packages` or `yarn bump-all-updated-packages --release-branch-cutoff`
+
+#### Pseudocode
+
+```
+check that no git changes are present
+
+for each package:
+    if package is private -> skip
+
+    if release-branch-cutoff argument is provided:
+        bump package version to the next minor
+        return
+
+    grep id of the last commit that changed package
+    grep id of the last commit that changed version of the package
+
+    if these ids are different:
+        bump package version (minor or patch)
+
+align packages versions across whole monorepo
+commit changes if required
+```
+
+### Notes
+
+At the final step you will be asked if you want to commit all these changes. Always confirm committing if you want these packages to be published then on CircleCI, because the workflow that does this [will check that commit has a tag inside its message](https://github.com/facebook/react-native/wiki/Release-and-its-automated-processes#notes-1).
+
+Updated versions will also be updated in packages consumers. This means if `@react-native/x` has `@react-native/y` as a dependency and we bump version of `@react-native/y`, then `@react-native/x` will have updated version of `@react-native/y` specified.
+
+## Publishing an updated package to npm
+
+We have a [CircleCI workflow](https://github.com/facebook/react-native/blob/292268ea3fa429cd1a1245b6239e0a85b59da02a/.circleci/config.yml#L1801-L1804), which runs **only on main or stable-\* branches**.
+
+#### Pseudocode
+
+```
+for each package:
+    if last commit contains version change:
+        if this commit has specific message:
+            publish package to npm
+```
+
+#### Notes
+
+This workflow explicitly checks that commit has a specific [tag](https://github.com/facebook/react-native/blob/main/scripts/monorepo/constants.js#L11) inside its message. This is used to prevent accidental publishes. To create such specific commit you should use [script from above](https://github.com/facebook/react-native/wiki/Release-and-its-automated-processes#finding-all-packages-that-have-unpublished-changes).
+
+If you want to bump package version and publish it to npm registry, your version change should be exactly in the last commit. This is because of two things:
+
+1. If multiple commits are merged to `main` branch at the same time, CircleCI will execute workflows only once on top of the latest commit.
+2. To determine that version was changed we [evaluate the difference between HEAD and HEAD~1](https://github.com/facebook/react-native/blob/daeee2a6619db59391de3b7c6e08db0dbe2331aa/scripts/monorepo/find-and-publish-all-bumped-packages.js#L32-L35).
+
+Example script output, where no package versions were changed:
+<img width="800" alt="Screenshot 2023-01-03 at 12 21 01" src="https://user-images.githubusercontent.com/28902667/210362611-97530b4d-0405-499c-9a3c-5542e069e929.png" />
+
+## Align package versions across monorepo
+
+> Side note: We do not anticipate that this script might be useful in future. With current monorepo setup, all packages versions should be updated and aligned by using `bump-all-updated-packages` script, both in `main` and `*-stable` branches.
+
+#### Use case
+
+You (or someone from release cycle team) want to verify that the latest versions of @react-native/\* packages are specified across monorepo, including `template`.
+
+#### How to execute
+
+`yarn align-package-versions`
+
+#### Pseudocode
+
+```
+check that no git changes are present
+
+for each package x:
+   for each package y:
+       if y has x as dependency:
+           validate that y uses the latest version of x
+```

website/sidebarsContributing.json

@@ -49,7 +49,8 @@
             "release-candidate-patch",
             "release-stable-minor",
             "release-stable-patch",
-            "release-troubleshooting"
+            "release-troubleshooting",
+            "release-updating-packages"
           ]
         }
       ]