DevTools build script enhancements (#17653)

* Updated DevTools local development instructions to mention experimental build step

* Added a command to download latest experimental release (for DevTools)

* Updated build instructions for clarity

* Added build-for-devtools package alias

package.json

@@ -98,6 +98,7 @@
   },
   "scripts": {
     "build": "node ./scripts/rollup/build.js",
+    "build-for-devtools": "cross-env RELEASE_CHANNEL=experimental yarn build -- react/index,react-dom,react-is,react-debug-tools,scheduler,react-test-renderer --type=NODE",
     "linc": "node ./scripts/tasks/linc.js",
     "lint": "node ./scripts/tasks/eslint.js",
     "lint-build": "node ./scripts/rollup/validate/index.js",

packages/react-devtools-extensions/README.md

@@ -6,16 +6,26 @@ The easiest way to install this extension is as a browser add-on:
 * [Chrome web store](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi?hl=en)
 * [Firefox Add-ons](https://addons.mozilla.org/en-US/firefox/addon/react-devtools/)
 
-## Development
-
+## Local development
 You can also build and install this extension from source.
 
-DevTools embeds local versions of several NPM packages also in this workspace. If you have not already built them, you'll need to do that before getting started by running the following command in the root directory of this repository:
-```sh
-yarn build -- react,react-dom,react-is,scheduler --type=NODE
-```
+### Prerequisite steps
+DevTools depends on local versions of several NPM packages<sup>1</sup> also in this workspace. You'll need to either build or download those packages first.
 
-Once the above packages have been built, you can build the extension by running:
+<sup>1</sup> Note that at this time, an _experimental_ build is required because DevTools depends on the `createRoot` API.
+
+#### Build from source
+To build dependencies from source, run the following command from the root of the repository:
+```sh
+yarn build-for-devtools
+```
+#### Download from CI
+To use the latest build from CI, run the following command from the root of the repository:
+```sh
+./scripts/release/download-experimental-build.js
+```
+### Build steps
+Once the above packages have been built or downloaded, you can build the extension by running:
 ```sh
 cd packages/react-devtools-extensions/
 

packages/react-devtools-inline/README.md

@@ -153,9 +153,28 @@ iframe.onload = () => {
 };
 ```
 
-## Development
+## Local development
+You can also build and test this package from source.
 
-Watch for changes made to the source code and rebuild:
+### Prerequisite steps
+DevTools depends on local versions of several NPM packages<sup>1</sup> also in this workspace. You'll need to either build or download those packages first.
+
+<sup>1</sup> Note that at this time, an _experimental_ build is required because DevTools depends on the `createRoot` API.
+
+#### Build from source
+To build dependencies from source, run the following command from the root of the repository:
+```sh
+yarn build-for-devtools
+```
+#### Download from CI
+To use the latest build from CI, run the following command from the root of the repository:
+```sh
+./scripts/release/download-experimental-build.js
+```
+### Build steps
+Once the above packages have been built or downloaded, you can watch for changes made to the source code and automatically rebuild by running:
 ```sh
 yarn start
-```
+```
+
+To test package changes, refer to the [`react-devtools-shell` README](https://github.com/facebook/react/blob/master/packages/react-devtools-shell/README.md).

packages/react-devtools-shell/README.md

@@ -2,14 +2,9 @@ Harness for testing local changes to the `react-devtools-inline` and `react-devt
 
 ## Development
 
-This target should be run in parallel with the `react-devtools-inline` package. The first step then is to watch for changes to that target:
-```sh
-cd packages/react-devtools-inline 
+This target should be run in parallel with the `react-devtools-inline` package. The first step then is to run that target following the instructions in the [`react-devtools-inline` README](https://github.com/facebook/react/blob/master/packages/react-devtools-inline/README.md).
 
-yarn start
-```
-
-Next, watch for changes to the test harness:
+The test harness can then be run as follows:
 ```sh
 cd packages/react-devtools-shell
 

packages/react-devtools/README.md

@@ -109,7 +109,26 @@ Or you could develop with a local HTTP server [like `serve`](https://www.npmjs.c
 
 **If you still have issues** please [report them](https://github.com/facebook/react/issues/new?labels=Component:%20Developer%20Tools). Don't forget to specify your OS, browser version, extension version, and the exact instructions to reproduce the issue with a screenshot.
 
-## Development
+## Local development
+The standalone DevTools app can be built and tested from source following the instructions below.
+
+### Prerequisite steps
+DevTools depends on local versions of several NPM packages<sup>1</sup> also in this workspace. You'll need to either build or download those packages first.
+
+<sup>1</sup> Note that at this time, an _experimental_ build is required because DevTools depends on the `createRoot` API.
+
+#### Build from source
+To build dependencies from source, run the following command from the root of the repository:
+```sh
+yarn build-for-devtools
+```
+#### Download from CI
+To use the latest build from CI, run the following command from the root of the repository:
+```sh
+./scripts/release/download-experimental-build.js
+```
+### Build steps
+Once the above packages have been built or downloaded, you can test the standalone DevTools by running the following:
 
 * Run `yarn start:backend` and `yarn start:standalone` in `../react-devtools-core`
 * Run `yarn start` in this folder

scripts/release/download-experimental-build-commands/print-summary.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const clear = require('clear');
+const {join, relative} = require('path');
+const theme = require('../theme');
+
+module.exports = ({build}) => {
+  const commandPath = relative(
+    process.env.PWD,
+    join(__dirname, '../download-experimental-build.js')
+  );
+
+  clear();
+
+  const message = theme`
+    {caution An experimental build has been downloaded!}
+
+    You can download this build again by running:
+    {path   ${commandPath}} --build={build ${build}}
+  `;
+
+  console.log(message.replace(/\n +/g, '\n').trim());
+};

scripts/release/download-experimental-build.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const {join} = require('path');
+const {getPublicPackages, handleError} = require('./utils');
+
+const checkEnvironmentVariables = require('./shared-commands/check-environment-variables');
+const downloadBuildArtifacts = require('./shared-commands/download-build-artifacts');
+const getLatestMasterBuildNumber = require('./shared-commands/get-latest-master-build-number');
+const parseParams = require('./shared-commands/parse-params');
+const printSummary = require('./download-experimental-build-commands/print-summary');
+
+const run = async () => {
+  try {
+    const params = parseParams();
+    params.cwd = join(__dirname, '..', '..');
+    params.packages = await getPublicPackages();
+
+    if (!params.build) {
+      params.build = await getLatestMasterBuildNumber(true);
+    }
+
+    await checkEnvironmentVariables(params);
+    await downloadBuildArtifacts(params);
+
+    printSummary(params);
+  } catch (error) {
+    handleError(error);
+  }
+};
+
+run();

scripts/release/prepare-canary.js

@@ -5,10 +5,10 @@
 const {join} = require('path');
 const {getPublicPackages, handleError} = require('./utils');
 
-const checkEnvironmentVariables = require('./prepare-canary-commands/check-environment-variables');
-const downloadBuildArtifacts = require('./prepare-canary-commands/download-build-artifacts');
-const getLatestMasterBuildNumber = require('./prepare-canary-commands/get-latest-master-build-number');
-const parseParams = require('./prepare-canary-commands/parse-params');
+const checkEnvironmentVariables = require('./shared-commands/check-environment-variables');
+const downloadBuildArtifacts = require('./shared-commands/download-build-artifacts');
+const getLatestMasterBuildNumber = require('./shared-commands/get-latest-master-build-number');
+const parseParams = require('./shared-commands/parse-params');
 const printPrereleaseSummary = require('./shared-commands/print-prerelease-summary');
 const testPackagingFixture = require('./shared-commands/test-packaging-fixture');
 const testTracingFixture = require('./shared-commands/test-tracing-fixture');
@@ -20,7 +20,7 @@ const run = async () => {
     params.packages = await getPublicPackages();
 
     if (!params.build) {
-      params.build = await getLatestMasterBuildNumber();
+      params.build = await getLatestMasterBuildNumber(false);
     }
 
     await checkEnvironmentVariables(params);

scripts/release/shared-commands/get-latest-master-build-number.js

@@ -5,7 +5,11 @@
 const http = require('request-promise-json');
 const {logPromise} = require('../utils');
 
-const run = async () => {
+const run = async useExperimentalBuild => {
+  const targetJobName = useExperimentalBuild
+    ? 'process_artifacts_experimental'
+    : 'process_artifacts';
+
   // https://circleci.com/docs/api/#recent-builds-for-a-project-branch
   const metadataURL = `https://circleci.com/api/v1.1/project/github/facebook/react/tree/master`;
   const metadata = await http.get(metadataURL, true);
@@ -13,7 +17,7 @@ const run = async () => {
     entry =>
       entry.branch === 'master' &&
       entry.status === 'success' &&
-      entry.workflows.job_name === 'process_artifacts'
+      entry.workflows.job_name === targetJobName
   ).build_num;
 
   return build;