Merge pull request #2376 from microsoft/octogonz/rush-graduate-experimental

[rush] Remove the "experimental" label from "rush deploy" and "rush version"

Author: octogonz

apps/rush-lib/src/cli/actions/DeployAction.ts

@@ -24,10 +24,10 @@ export class DeployAction extends BaseRushAction {
     super({
       actionName: 'deploy',
       summary:
-        '(EXPERIMENTAL) Prepares a deployment by copying a subset of Rush projects and their dependencies' +
+        'Prepares a deployment by copying a subset of Rush projects and their dependencies' +
         ' to a target folder',
       documentation:
-        '(EXPERIMENTAL) After building the repo, "rush deploy" can be used to prepare a deployment by copying' +
+        'After building the repo, "rush deploy" can be used to prepare a deployment by copying' +
         ' a subset of Rush projects and their dependencies to a target folder, which can then be uploaded to' +
         ' a production server.  The "rush deploy" behavior is specified by a scenario config file that must' +
         ' be created first, using the "rush init-deploy" command.',

apps/rush-lib/src/cli/actions/InitDeployAction.ts

@@ -21,9 +21,9 @@ export class InitDeployAction extends BaseRushAction {
   public constructor(parser: RushCommandLineParser) {
     super({
       actionName: 'init-deploy',
-      summary: '(EXPERIMENTAL) Creates a deployment scenario config file for use with "rush deploy".',
+      summary: 'Creates a deployment scenario config file for use with "rush deploy".',
       documentation:
-        '(EXPERIMENTAL) Use this command to initialize a new scenario config file for use with "rush deploy".' +
+        'Use this command to initialize a new scenario config file for use with "rush deploy".' +
         ' The default filename is common/config/rush/deploy.json. However, if you need to manage multiple' +
         ' deployments with different settings, you can use use "--scenario" to create additional config files.',
       parser

apps/rush-lib/src/cli/actions/ScanAction.ts

@@ -15,16 +15,18 @@ export class ScanAction extends BaseConfiglessRushAction {
   public constructor(parser: RushCommandLineParser) {
     super({
       actionName: 'scan',
-      summary: 'Scan the current project folder and display a report of imported packages.',
+      summary:
+        'When migrating projects into a Rush repo, this command is helpful for detecting' +
+        ' undeclared dependencies.',
       documentation:
-        `The NPM system allows a project to import dependencies without explicitly` +
-        ` listing them in its package.json file. This is a dangerous practice, because` +
-        ` there is no guarantee you will get a compatible version. The "rush scan" command` +
-        ` reports a list of packages that are imported by your code, which you can` +
-        ` compare against your package.json file to find mistakes. It searches the "./src"` +
-        ` and "./lib" folders for typical import syntaxes such as "import __ from '__'",` +
-        ` "require('__')", "System.import('__'), etc.  The results are only approximate,` +
-        ` but generally pretty accurate.`,
+        `The Node.js module system allows a project to import NPM packages without explicitly` +
+        ` declaring them as dependencies in the package.json file.  Such "phantom dependencies"` +
+        ` can cause problems.  Rush and PNPM use symlinks specifically to protect against phantom dependencies.` +
+        ` These protections may cause runtime errors for existing projects when they are first migrated into` +
+        ` a Rush monorepo.  The "rush scan" command is a handy tool for fixing these errors. It scans the "./src"` +
+        ` and "./lib" folders for import syntaxes such as "import __ from '__'", "require('__')",` +
+        ` and "System.import('__').  It prints a report of the referenced packages.  This heuristic is` +
+        ` not perfect, but it can save a lot of time when migrating projects.`,
       safeForSimultaneousRushProcesses: true,
       parser
     });

apps/rush-lib/src/cli/actions/VersionAction.ts

@@ -36,9 +36,8 @@ export class VersionAction extends BaseRushAction {
   public constructor(parser: RushCommandLineParser) {
     super({
       actionName: 'version',
-      summary: '(EXPERIMENTAL) Manage package versions in the repo.',
-      documentation:
-        '(EXPERIMENTAL) use this "rush version" command to ensure version policies and bump versions.',
+      summary: 'Manage package versions in the repo.',
+      documentation: 'use this "rush version" command to ensure version policies and bump versions.',
       parser
     });
   }

apps/rush-lib/src/cli/test/__snapshots__/CommandLineHelp.test.ts.snap

@@ -23,13 +23,12 @@ Positional arguments:
     check               Checks each project's package.json files and ensures 
                         that all dependencies are of the same version 
                         throughout the repository.
-    deploy              (EXPERIMENTAL) Prepares a deployment by copying a 
-                        subset of Rush projects and their dependencies to a 
-                        target folder
+    deploy              Prepares a deployment by copying a subset of Rush 
+                        projects and their dependencies to a target folder
     init                Initializes a new repository to be managed by Rush
     init-autoinstaller  Initializes a new autoinstaller
-    init-deploy         (EXPERIMENTAL) Creates a deployment scenario config 
-                        file for use with \\"rush deploy\\".
+    init-deploy         Creates a deployment scenario config file for use 
+                        with \\"rush deploy\\".
     install             Install package dependencies for all projects in the 
                         repo according to the shrinkwrap file
     link                Create node_modules symlinks for all projects
@@ -38,16 +37,17 @@ Positional arguments:
                         requests generated by \\"rush change\\".
     purge               For diagnostic purposes, use this command to delete 
                         caches and other temporary files used by Rush
-    scan                Scan the current project folder and display a report 
-                        of imported packages.
+    scan                When migrating projects into a Rush repo, this 
+                        command is helpful for detecting undeclared 
+                        dependencies.
     unlink              Delete node_modules symlinks for all projects in the 
                         repo
     update              Install package dependencies for all projects in the 
                         repo, and create or update the shrinkwrap file as 
                         needed
     update-autoinstaller
                         Updates autoinstaller package dependenices
-    version             (EXPERIMENTAL) Manage package versions in the repo.
+    version             Manage package versions in the repo.
     import-strings      Imports translated strings into each project.
     upload              Uploads the built files to the server
     build               Build all projects that haven't been built, or have 
@@ -241,11 +241,11 @@ exports[`CommandLineHelp prints the help for each action: deploy 1`] = `
                    [-t PATH] [--create-archive ARCHIVE_PATH]
                    
 
-(EXPERIMENTAL) After building the repo, \\"rush deploy\\" can be used to prepare 
-a deployment by copying a subset of Rush projects and their dependencies to a 
-target folder, which can then be uploaded to a production server. The \\"rush 
-deploy\\" behavior is specified by a scenario config file that must be created 
-first, using the \\"rush init-deploy\\" command.
+After building the repo, \\"rush deploy\\" can be used to prepare a deployment by 
+copying a subset of Rush projects and their dependencies to a target folder, 
+which can then be uploaded to a production server. The \\"rush deploy\\" behavior 
+is specified by a scenario config file that must be created first, using the 
+\\"rush init-deploy\\" command.
 
 Optional arguments:
   -h, --help            Show this help message and exit.
@@ -372,10 +372,10 @@ Optional arguments:
 exports[`CommandLineHelp prints the help for each action: init-deploy 1`] = `
 "usage: rush init-deploy [-h] -p PROJECT_NAME [-s SCENARIO]
 
-(EXPERIMENTAL) Use this command to initialize a new scenario config file for 
-use with \\"rush deploy\\". The default filename is common/config/rush/deploy.
-json. However, if you need to manage multiple deployments with different 
-settings, you can use use \\"--scenario\\" to create additional config files.
+Use this command to initialize a new scenario config file for use with \\"rush 
+deploy\\". The default filename is common/config/rush/deploy.json. However, if 
+you need to manage multiple deployments with different settings, you can use 
+use \\"--scenario\\" to create additional config files.
 
 Optional arguments:
   -h, --help            Show this help message and exit.
@@ -657,14 +657,16 @@ Optional arguments:
 exports[`CommandLineHelp prints the help for each action: scan 1`] = `
 "usage: rush scan [-h]
 
-The NPM system allows a project to import dependencies without explicitly 
-listing them in its package.json file. This is a dangerous practice, because 
-there is no guarantee you will get a compatible version. The \\"rush scan\\" 
-command reports a list of packages that are imported by your code, which you 
-can compare against your package.json file to find mistakes. It searches the 
-\\"./src\\" and \\"./lib\\" folders for typical import syntaxes such as \\"import __ 
-from '__'\\", \\"require('__')\\", \\"System.import('__'), etc. The results are only 
-approximate, but generally pretty accurate.
+The Node.js module system allows a project to import NPM packages without 
+explicitly declaring them as dependencies in the package.json file. Such 
+\\"phantom dependencies\\" can cause problems. Rush and PNPM use symlinks 
+specifically to protect against phantom dependencies. These protections may 
+cause runtime errors for existing projects when they are first migrated into 
+a Rush monorepo. The \\"rush scan\\" command is a handy tool for fixing these 
+errors. It scans the \\"./src\\" and \\"./lib\\" folders for import syntaxes such as 
+\\"import __ from '__'\\", \\"require('__')\\", and \\"System.import('__'). It prints a 
+report of the referenced packages. This heuristic is not perfect, but it can 
+save a lot of time when migrating projects.
 
 Optional arguments:
   -h, --help  Show this help message and exit.
@@ -800,8 +802,7 @@ exports[`CommandLineHelp prints the help for each action: version 1`] = `
                     [--override-bump BUMPTYPE] [--override-prerelease-id ID]
                     
 
-(EXPERIMENTAL) use this \\"rush version\\" command to ensure version policies and 
-bump versions.
+use this \\"rush version\\" command to ensure version policies and bump versions.
 
 Optional arguments:
   -h, --help            Show this help message and exit.

common/changes/@microsoft/rush/octogonz-rush-graduate-experimental_2020-12-01-22-36.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "Remove the \"experimental\" label from some Rush commands that are now stable.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush",
+  "email": "[email protected]"
+}