Reorganise and document release script entry points (#42774)

Summary:
Pull Request resolved: https://github.com/facebook/react-native/pull/42774

Reorganise release scripts so that command entry points are grouped based on execution context, which also reflects dependencies between scripts.

Also:

- Document the current behaviours of these scripts.
- Relocate utils out of the root contents.
- Replace `exec` call to `set-rn-version` script with function import.

NOTE: `yarn trigger-react-native-release` (documented command in release process) is unchanged, since this is aliased from `package.json`.

```
├── releases
│   ├── templates/
│   ├── utils/
│   ├── remove-new-arch-flags.js
│   ├── set-rn-version.js
│   └── update-template-package.js
├── releases-ci
│   ├── prepare-package-for-release.js
│   └── publish-npm.js
└── releases-local
    └── trigger-react-native-release.js
```

Changelog: [Internal]

Reviewed By: cipolleschi

Differential Revision: D53274341

fbshipit-source-id: eec2befc43e7a47fd821b2e2bcc818ddffbb6cf7

.circleci/configurations/jobs.yml

@@ -1180,7 +1180,7 @@ jobs:
               echo "Using the version from the package.json: $VERSION"
             fi
 
-            node ./scripts/prepare-package-for-release.js -v "$VERSION" -l << parameters.latest >> --dry-run << parameters.dryrun >>
+            node ./scripts/releases-ci/prepare-package-for-release.js -v "$VERSION" -l << parameters.latest >> --dry-run << parameters.dryrun >>
 
   build_npm_package:
     parameters:
@@ -1250,7 +1250,7 @@ jobs:
                   else
                     export ORG_GRADLE_PROJECT_reactNativeArchitectures="armeabi-v7a,arm64-v8a,x86,x86_64"
                   fi
-                  node ./scripts/publish-npm.js -t << parameters.release_type >>
+                  node ./scripts/releases-ci/publish-npm.js -t << parameters.release_type >>
 
       - run:
           name: Zip Maven Artifacts from /tmp/maven-local

package.json

@@ -38,7 +38,7 @@
     "test-typescript-offline": "dtslint --localTs node_modules/typescript/lib  packages/react-native/types",
     "test-typescript": "dtslint packages/react-native/types",
     "test": "jest",
-    "trigger-react-native-release": "node ./scripts/trigger-react-native-release.js",
+    "trigger-react-native-release": "node ./scripts/releases-local/trigger-react-native-release.js",
     "update-lock": "npx yarn-deduplicate"
   },
   "workspaces": [

scripts/npm-utils.js

@@ -10,7 +10,7 @@
 
 'use strict';
 
-const {parseVersion} = require('./releases/version-utils');
+const {parseVersion} = require('./releases/utils/version-utils');
 const {
   exitIfNotOnGit,
   getCurrentCommit,

scripts/prepare-package-for-release.js

@@ -1,134 +0,0 @@
-/**
- * Copyright (c) Meta Platforms, Inc. and affiliates.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- *
- * @flow
- * @format
- */
-
-'use strict';
-
-const {failIfTagExists} = require('./release-utils');
-const {isReleaseBranch, parseVersion} = require('./releases/version-utils');
-/**
- * This script prepares a release package to be pushed to npm
- * It is triggered to run on CircleCI
- * It will:
- *    * It updates the version in json/gradle files and makes sure they are consistent between each other (set-rn-version)
- *    * Updates podfile for RNTester
- *    * Commits changes and tags with the next version based off of last version tag.
- *      This in turn will trigger another CircleCI job to publish to npm
- */
-const {echo, exec, exit} = require('shelljs');
-const yargs = require('yargs');
-
-const argv = yargs
-  .option('r', {
-    alias: 'remote',
-    default: 'origin',
-  })
-  .option('v', {
-    alias: 'to-version',
-    type: 'string',
-    required: true,
-  })
-  .option('l', {
-    alias: 'latest',
-    type: 'boolean',
-    default: false,
-  })
-  .option('d', {
-    alias: 'dry-run',
-    type: 'boolean',
-    default: false,
-  }).argv;
-
-const branch = process.env.CIRCLE_BRANCH;
-// $FlowFixMe[prop-missing]
-const remote = argv.remote;
-// $FlowFixMe[prop-missing]
-const releaseVersion = argv.toVersion;
-// $FlowFixMe[prop-missing]
-const isLatest = argv.latest;
-// $FlowFixMe[prop-missing]
-const isDryRun = argv.dryRun;
-
-if (branch == null) {
-  throw new Error('process.env.CIRCLE_BRANCH is not set');
-}
-
-const buildType = isDryRun
-  ? 'dry-run'
-  : isReleaseBranch(branch)
-  ? 'release'
-  : 'nightly';
-
-failIfTagExists(releaseVersion, buildType);
-
-if (branch && !isReleaseBranch(branch) && !isDryRun) {
-  console.error(`This needs to be on a release branch. On branch: ${branch}`);
-  exit(1);
-} else if (!branch && !isDryRun) {
-  console.error('This needs to be on a release branch.');
-  exit(1);
-}
-
-const {version} = parseVersion(releaseVersion, buildType);
-if (version == null) {
-  console.error(`Invalid version provided: ${releaseVersion}`);
-  exit(1);
-}
-
-if (
-  exec(
-    `node scripts/releases/set-rn-version.js --to-version ${version} --build-type ${buildType}`,
-  ).code
-) {
-  echo(`Failed to set React Native version to ${version}`);
-  exit(1);
-}
-
-// Release builds should commit the version bumps, and create tags.
-echo('Updating RNTester Podfile.lock...');
-if (exec('source scripts/update_podfile_lock.sh && update_pods').code) {
-  echo('Failed to update RNTester Podfile.lock.');
-  echo('Fix the issue, revert and try again.');
-  exit(1);
-}
-
-echo(`Local checkout has been prepared for release version ${version}.`);
-if (isDryRun) {
-  echo('Changes will not be committed because --dry-run was set to true.');
-  exit(0);
-}
-
-// Make commit [0.21.0-rc] Bump version numbers
-if (exec(`git commit -a -m "[${version}] Bump version numbers"`).code) {
-  echo('failed to commit');
-  exit(1);
-}
-
-// Add tag v0.21.0-rc.1
-if (exec(`git tag -a v${version} -m "v${version}"`).code) {
-  echo(
-    `failed to tag the commit with v${version}, are you sure this release wasn't made earlier?`,
-  );
-  echo('You may want to rollback the last commit');
-  echo('git reset --hard HEAD~1');
-  exit(1);
-}
-
-// If `isLatest`, this git tag will also set npm release as `latest`
-if (isLatest) {
-  exec('git tag -d latest');
-  exec(`git push ${remote} :latest`);
-
-  // This will be pushed with the `--follow-tags`
-  exec('git tag -a latest -m "latest"');
-}
-
-exec(`git push ${remote} ${branch} --follow-tags`);
-
-exit(0);

scripts/releases-ci/README.md

@@ -0,0 +1,15 @@
+# scripts/releases-ci
+
+CI-only release scripts — intended to run from a CI workflow (CircleCI or GitHub Actions).
+
+## Commands
+
+For information on command arguments, run `node <command> --help`.
+
+### `prepare-package-for-release.js`
+
+Prepares files within the `react-native` package and template for the target release version. Writes a new commit and tag, which will trigger `publish-npm.js` in a new workflow.
+
+### `publish-npm.js`
+
+Prepares release artifacts and publishes the `react-native` package to npm.

scripts/releases-ci/__tests__/publish-npm-test.js

@@ -5,6 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  *
  * @format
+ * @oncall react_native
  */
 
 const execMock = jest.fn();
@@ -23,24 +24,27 @@ jest
     echo: echoMock,
     exit: exitMock,
   }))
-  .mock('./../scm-utils', () => ({
+  .mock('./../../scm-utils', () => ({
     exitIfNotOnGit: command => command(),
     getCurrentCommit: () => 'currentco_mmit',
     isTaggedLatest: isTaggedLatestMock,
   }))
   .mock('path', () => ({
-    join: () => '../packages/react-native',
+    ...jest.requireActual('path'),
+    join: () => '../../packages/react-native',
   }))
   .mock('fs')
-  .mock('./../release-utils', () => ({
+  .mock('../../releases/utils/release-utils', () => ({
     generateAndroidArtifacts: jest.fn(),
     publishAndroidArtifactsToMaven: publishAndroidArtifactsToMavenMock,
   }))
-  .mock('./../releases/set-rn-version', () => ({
+  .mock('../../releases/set-rn-version', () => ({
     setReactNativeVersion: setReactNativeVersionMock,
   }))
-  .mock('../monorepo/get-and-update-packages')
-  .mock('../releases/remove-new-arch-flags', () => removeNewArchFlags);
+  .mock('../../monorepo/get-and-update-packages')
+  .mock('../../releases/remove-new-arch-flags', () => ({
+    removeNewArchFlags,
+  }));
 
 const date = new Date('2023-04-20T23:52:39.543Z');
 
@@ -67,8 +71,8 @@ describe('publish-npm', () => {
   });
 
   describe('publish-npm.js', () => {
-    it('Fails when invalid build type is passed', () => {
-      expect(publishNpm('invalid')).rejects.toThrow(
+    it('Fails when invalid build type is passed', async () => {
+      await expect(publishNpm('invalid')).rejects.toThrow(
         'Unsupported build type: invalid',
       );
     });
@@ -138,9 +142,9 @@ describe('publish-npm', () => {
   });
 
   describe('release', () => {
-    it('should fail with invalid release version', () => {
+    it('should fail with invalid release version', async () => {
       process.env.CIRCLE_TAG = '1.0.1';
-      expect(publishNpm('release')).rejects.toThrow(
+      await expect(publishNpm('release')).rejects.toThrow(
         'Version 1.0.1 is not valid for Release',
       );
       expect(publishAndroidArtifactsToMavenMock).not.toBeCalled();
@@ -162,7 +166,7 @@ describe('publish-npm', () => {
       );
       expect(execMock).toHaveBeenCalledWith(
         `npm publish --tag 0.81-stable --otp otp`,
-        {cwd: '../packages/react-native'},
+        {cwd: '../../packages/react-native'},
       );
       expect(echoMock).toHaveBeenCalledWith(
         `Published to npm ${expectedVersion}`,
@@ -187,7 +191,7 @@ describe('publish-npm', () => {
       );
       expect(execMock).toHaveBeenCalledWith(
         `npm publish --tag latest --otp ${process.env.NPM_CONFIG_OTP}`,
-        {cwd: '../packages/react-native'},
+        {cwd: '../../packages/react-native'},
       );
       expect(echoMock).toHaveBeenCalledWith(
         `Published to npm ${expectedVersion}`,
@@ -212,7 +216,7 @@ describe('publish-npm', () => {
       );
       expect(execMock).toHaveBeenCalledWith(
         `npm publish --tag latest --otp ${process.env.NPM_CONFIG_OTP}`,
-        {cwd: '../packages/react-native'},
+        {cwd: '../../packages/react-native'},
       );
       expect(echoMock).toHaveBeenCalledWith(`Failed to publish package to npm`);
       expect(exitMock).toHaveBeenCalledWith(1);
@@ -235,7 +239,7 @@ describe('publish-npm', () => {
       );
       expect(execMock).toHaveBeenCalledWith(
         `npm publish --tag next --otp ${process.env.NPM_CONFIG_OTP}`,
-        {cwd: '../packages/react-native'},
+        {cwd: '../../packages/react-native'},
       );
       expect(echoMock).toHaveBeenCalledWith(
         `Published to npm ${expectedVersion}`,

scripts/releases-ci/prepare-package-for-release.js

@@ -0,0 +1,142 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ * @format
+ * @oncall react_native
+ */
+
+'use strict';
+
+const {setReactNativeVersion} = require('../releases/set-rn-version');
+const {failIfTagExists} = require('../releases/utils/release-utils');
+const {
+  isReleaseBranch,
+  parseVersion,
+} = require('../releases/utils/version-utils');
+const {echo, exec, exit} = require('shelljs');
+const yargs = require('yargs');
+
+/**
+ * This script prepares a release package to be pushed to npm
+ * It is triggered to run on CircleCI
+ * It will:
+ *    * It updates the version in json/gradle files and makes sure they are consistent between each other (set-rn-version)
+ *    * Updates podfile for RNTester
+ *    * Commits changes and tags with the next version based off of last version tag.
+ *      This in turn will trigger another CircleCI job to publish to npm
+ */
+async function main() {
+  const argv = yargs
+    .option('r', {
+      alias: 'remote',
+      default: 'origin',
+    })
+    .option('v', {
+      alias: 'to-version',
+      type: 'string',
+      required: true,
+    })
+    .option('l', {
+      alias: 'latest',
+      type: 'boolean',
+      default: false,
+    })
+    .option('d', {
+      alias: 'dry-run',
+      type: 'boolean',
+      default: false,
+    }).argv;
+
+  const branch = process.env.CIRCLE_BRANCH;
+  // $FlowFixMe[prop-missing]
+  const remote = argv.remote;
+  // $FlowFixMe[prop-missing]
+  const releaseVersion = argv.toVersion;
+  // $FlowFixMe[prop-missing]
+  const isLatest = argv.latest;
+  // $FlowFixMe[prop-missing]
+  const isDryRun = argv.dryRun;
+
+  if (branch == null) {
+    throw new Error('process.env.CIRCLE_BRANCH is not set');
+  }
+
+  const buildType = isDryRun
+    ? 'dry-run'
+    : isReleaseBranch(branch)
+    ? 'release'
+    : 'nightly';
+
+  failIfTagExists(releaseVersion, buildType);
+
+  if (branch && !isReleaseBranch(branch) && !isDryRun) {
+    console.error(`This needs to be on a release branch. On branch: ${branch}`);
+    exit(1);
+  } else if (!branch && !isDryRun) {
+    console.error('This needs to be on a release branch.');
+    exit(1);
+  }
+
+  const {version} = parseVersion(releaseVersion, buildType);
+  if (version == null) {
+    console.error(`Invalid version provided: ${releaseVersion}`);
+    exit(1);
+  }
+
+  try {
+    await setReactNativeVersion(version, null, buildType);
+  } catch (e) {
+    echo(`Failed to set React Native version to ${version}`);
+    exit(1);
+  }
+
+  // Release builds should commit the version bumps, and create tags.
+  echo('Updating RNTester Podfile.lock...');
+  if (exec('source scripts/update_podfile_lock.sh && update_pods').code) {
+    echo('Failed to update RNTester Podfile.lock.');
+    echo('Fix the issue, revert and try again.');
+    exit(1);
+  }
+
+  echo(`Local checkout has been prepared for release version ${version}.`);
+  if (isDryRun) {
+    echo('Changes will not be committed because --dry-run was set to true.');
+    exit(0);
+  }
+
+  // Make commit [0.21.0-rc] Bump version numbers
+  if (exec(`git commit -a -m "[${version}] Bump version numbers"`).code) {
+    echo('failed to commit');
+    exit(1);
+  }
+
+  // Add tag v0.21.0-rc.1
+  if (exec(`git tag -a v${version} -m "v${version}"`).code) {
+    echo(
+      `failed to tag the commit with v${version}, are you sure this release wasn't made earlier?`,
+    );
+    echo('You may want to rollback the last commit');
+    echo('git reset --hard HEAD~1');
+    exit(1);
+  }
+
+  // If `isLatest`, this git tag will also set npm release as `latest`
+  if (isLatest) {
+    exec('git tag -d latest');
+    exec(`git push ${remote} :latest`);
+
+    // This will be pushed with the `--follow-tags`
+    exec('git tag -a latest -m "latest"');
+  }
+
+  exec(`git push ${remote} ${branch} --follow-tags`);
+}
+
+if (require.main === module) {
+  // eslint-disable-next-line no-void
+  void main();
+}

scripts/releases-ci/publish-npm.js

@@ -4,28 +4,31 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @format
  * @flow
+ * @format
+ * @oncall react_native
  */
 
 'use strict';
 
 /*::
-import type {BuildType} from './releases/version-utils';
+import type {BuildType} from '../releases/utils/version-utils';
 */
 
-const getAndUpdatePackages = require('./monorepo/get-and-update-packages');
-const {getNpmInfo, publishPackage} = require('./npm-utils');
+const getAndUpdatePackages = require('../monorepo/get-and-update-packages');
+const {getNpmInfo, publishPackage} = require('../npm-utils');
+const {removeNewArchFlags} = require('../releases/remove-new-arch-flags');
+const {setReactNativeVersion} = require('../releases/set-rn-version');
 const {
   generateAndroidArtifacts,
   publishAndroidArtifactsToMaven,
-} = require('./release-utils');
-const removeNewArchFlags = require('./releases/remove-new-arch-flags');
-const {setReactNativeVersion} = require('./releases/set-rn-version');
+} = require('../releases/utils/release-utils');
 const path = require('path');
 const {echo, exit} = require('shelljs');
 const yargs = require('yargs');
 
+const REPO_ROOT = path.resolve(__dirname, '../..');
+
 /**
  * This script prepares a release version of react-native and may publish to NPM.
  * It is supposed to run in CI environment, not on a developer's machine.
@@ -101,7 +104,7 @@ async function publishNpm(buildType /*: BuildType */) /*: Promise<void> */ {
   // NPM publishing is done just after.
   publishAndroidArtifactsToMaven(version, buildType);
 
-  const packagePath = path.join(__dirname, '..', 'packages', 'react-native');
+  const packagePath = path.join(REPO_ROOT, 'packages', 'react-native');
   const result = publishPackage(packagePath, {
     // $FlowFixMe[incompatible-call]
     tags: [tag],

scripts/releases-local/README.md

@@ -0,0 +1,11 @@
+# scripts/releases-local
+
+Local-only release scripts.
+
+## Commands
+
+For information on command arguments, run `node <command> --help`.
+
+### `trigger-react-native-release.js`
+
+Trigger the external release publishing workflow on CircleCI.

scripts/releases-local/trigger-react-native-release.js

@@ -1,4 +1,3 @@
-#!/usr/bin/env node
 /**
  * Copyright (c) Meta Platforms, Inc. and affiliates.
  *
@@ -7,16 +6,20 @@
  *
  * @flow
  * @format
+ * @oncall react_native
  */
 
 'use strict';
 
-const detectPackageUnreleasedChanges = require('./monorepo/bump-all-updated-packages/bump-utils.js');
-const checkForGitChanges = require('./monorepo/check-for-git-changes');
-const forEachPackage = require('./monorepo/for-each-package');
-const {failIfTagExists} = require('./release-utils');
-const {isReleaseBranch, parseVersion} = require('./releases/version-utils');
-const {exitIfNotOnGit, getBranchName} = require('./scm-utils');
+const detectPackageUnreleasedChanges = require('../monorepo/bump-all-updated-packages/bump-utils.js');
+const checkForGitChanges = require('../monorepo/check-for-git-changes');
+const forEachPackage = require('../monorepo/for-each-package');
+const {failIfTagExists} = require('../releases/utils/release-utils');
+const {
+  isReleaseBranch,
+  parseVersion,
+} = require('../releases/utils/version-utils');
+const {exitIfNotOnGit, getBranchName} = require('../scm-utils');
 const chalk = require('chalk');
 const inquirer = require('inquirer');
 const path = require('path');

scripts/releases/README.md

@@ -0,0 +1,19 @@
+# scripts/releases
+
+Scripts related to creating a React Native release. These are the lower level entry points used by [**scripts/releases-ci**](https://github.com/facebook/react-native/tree/main/scripts/releases-ci).
+
+## Commands
+
+For information on command arguments, run `node <command> --help`.
+
+### `remove-new-arch-flags.js`
+
+Updates native build files to disable the New Architecture.
+
+### `set-rn-version.js`
+
+Updates relevant files in the `react-native` package and template to materialize the given release version.
+
+### `update-template-package.js`
+
+Updates local dependencies in the template `package.json`.

scripts/releases/__tests__/remove-new-arch-flags-test.js

@@ -8,7 +8,7 @@
  * @oncall react-native
  */
 
-const removeNewArchFlags = require('../remove-new-arch-flags');
+const {removeNewArchFlags} = require('../remove-new-arch-flags');
 const {
   expectedGradlePropertiesFile,
   expectedReactNativePodsFile,

scripts/releases/remove-new-arch-flags.js

@@ -101,7 +101,9 @@ function flipNewArchFlagForAndroid(
 }
 // ===============
 
-module.exports = removeNewArchFlags;
+module.exports = {
+  removeNewArchFlags,
+};
 
 if (require.main === module) {
   removeNewArchFlags();

scripts/releases/set-rn-version.js

@@ -10,12 +10,12 @@
  */
 
 /*::
-import type {BuildType, Version} from './version-utils';
+import type {BuildType, Version} from './utils/version-utils';
 */
 
 const {getNpmInfo} = require('../npm-utils');
 const updateTemplatePackage = require('./update-template-package');
-const {parseVersion, validateBuildType} = require('./version-utils');
+const {parseVersion, validateBuildType} = require('./utils/version-utils');
 const {parseArgs} = require('@pkgjs/parseargs');
 const {promises: fs} = require('fs');
 

scripts/releases/templates/RCTVersion.m-template.js

@@ -10,7 +10,7 @@
  */
 
 /*::
-import type {Version} from '../version-utils';
+import type {Version} from '../utils/version-utils';
 */
 
 module.exports = ({version} /*: {version: Version} */) /*: string */ => `/**

scripts/releases/templates/ReactNativeVersion.h-template.js

@@ -10,7 +10,7 @@
  */
 
 /*::
-import type {Version} from '../version-utils';
+import type {Version} from '../utils/version-utils';
 */
 
 module.exports = ({version} /*: {version: Version} */) /*: string */ => `/**

scripts/releases/templates/ReactNativeVersion.java-template.js

@@ -10,7 +10,7 @@
  */
 
 /*::
-import type {Version} from '../version-utils';
+import type {Version} from '../utils/version-utils';
 */
 
 module.exports = ({version} /*: {version: Version} */) /*: string */ => `/**

scripts/releases/templates/ReactNativeVersion.js-template.js

@@ -10,7 +10,7 @@
  */
 
 /*::
-import type {Version} from '../version-utils';
+import type {Version} from '../utils/version-utils';
 */
 
 module.exports = ({version} /*: {version: Version} */) /*: string */ => `/**

scripts/releases/utils/__tests__/version-utils-test.js

@@ -5,6 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  *
  * @format
+ * @oncall react_native
  */
 
 const {

scripts/releases/utils/release-utils.js

@@ -6,13 +6,14 @@
  *
  * @flow strict-local
  * @format
+ * @oncall react_native
  */
 
 'use strict';
 
 const {
   createHermesPrebuiltArtifactsTarball,
-} = require('../packages/react-native/scripts/hermes/hermes-utils');
+} = require('../../../packages/react-native/scripts/hermes/hermes-utils');
 const {echo, env, exec, exit, popd, pushd, test} = require('shelljs');
 
 /*::

scripts/releases/utils/version-utils.js

@@ -6,6 +6,7 @@
  *
  * @flow strict-local
  * @format
+ * @oncall react_native
  */
 
 const VERSION_REGEX = /^v?((\d+)\.(\d+)\.(\d+)(?:-(.+))?)$/;

scripts/testing-utils.js

@@ -6,6 +6,7 @@
  *
  * @flow strict-local
  * @format
+ * @oncall react_native
  */
 
 'use strict';
@@ -18,7 +19,7 @@ const circleCIArtifactsUtils = require('./circle-ci-artifacts-utils.js');
 const {
   generateAndroidArtifacts,
   generateiOSArtifacts,
-} = require('./release-utils');
+} = require('./releases/utils/release-utils');
 const fs = require('fs');
 // $FlowIgnore[cannot-resolve-module]
 const {spawn} = require('node:child_process');