chore: make manual publishing a bit better (#2666)

* chore: make manual publishing a bit better

* chore: update docs

* chore: add more publishing scripts info

Author: maribethb

gulpfile.js

@@ -48,7 +48,7 @@ function checkLicenses() {
 /**
  * Prepare for publishing. Must be run before any manual publish command.
  *
- * Clones blockly-samples, runs build and tests, logs into npm publish service.
+ * Clones blockly-samples, runs build and tests.
  * @param {Function} done Completed callback.
  */
 function prepareForPublish(done) {
@@ -82,11 +82,6 @@ function prepareForPublish(done) {
   console.log('Testing all plugins.');
   execSync('npm run test', {cwd: releaseDir, stdio: 'inherit'});
 
-  // Login to npm.
-  console.log('Logging in to npm.');
-  execSync(`npm login`, {
-    stdio: 'inherit',
-  });
   done();
 }
 
@@ -100,16 +95,15 @@ function exitIfNoReleaseDir(releaseDir, done) {
   if (!fs.existsSync(releaseDir)) {
     console.error(
       `No release directory ${releaseDir} exists. ` +
-        `Did you run 'npm run publish:prepare'?`,
+        `blockly-samples may not have been cloned correctly.`,
     );
     done();
     process.exit(1);
   }
 }
 
 /**
- * This script does not log into the npm publish service. If you haven't run
- * the prepare script recently, publishing will fail for that reason.
+ * Publishes plugins using lerna. MUST be run after `prepareForPublish`.
  * @param {boolean=} force True for forcing all plugins to publish, even ones
  *     that have not changed.
  * @returns {Function} Gulp task.
@@ -141,8 +135,8 @@ function publish(force) {
  * @param {Function} done Completed callback.
  * @returns {Function} Gulp task.
  */
-function publishManual(done) {
-  return publish(false)(done);
+function prepareAndPublish(done) {
+  return gulp.series(prepareForPublish, publish(false))(done);
 }
 
 /**
@@ -151,8 +145,8 @@ function publishManual(done) {
  * @param {Function} done Completed callback.
  * @returns {Function} Gulp task.
  */
-function forcePublish(done) {
-  return publish(true)(done);
+function prepareAndForcePublish(done) {
+  return gulp.series(prepareForPublish, publish(true))(done);
 }
 
 /**
@@ -178,6 +172,16 @@ function publishFromPackage(done) {
   done();
 }
 
+/**
+ * Publishes plugins that haven't been previously uploaded to npm.
+ * Also runs the prepare scripts to ensure plugins have been built and tested before publishing.
+ * @param {Function} done Completed callback.
+ * @returns {Function} Gulp task.
+ */
+function prepareAndPublishFromPackage(done) {
+  return gulp.series(prepareForPublish, publishFromPackage)(done);
+}
+
 /**
  * Runs lerna version to check which version numbers would be updated.
  * The version numbers will not be pushed and no tags or releases will
@@ -202,6 +206,15 @@ function checkVersions(done) {
   done();
 }
 
+/**
+ * Runs prepareForPublish and then checkVersions.
+ * @param {Function} done Completed callback.
+ * @returns {Function} Gulp task.
+ */
+function prepareAndCheckVersions(done) {
+  return gulp.series(prepareForPublish, checkVersions)(done);
+}
+
 /**
  * Deploy all plugins to gh-pages.
  * @param {string=} repo The repo to deploy to.
@@ -312,10 +325,10 @@ module.exports = {
   deployUpstream: deployToGhPagesUpstream,
   predeploy: predeployTasks.predeployAll,
   prepareForPublish: prepareForPublish,
-  publishManual: publishManual,
-  forcePublish: forcePublish,
-  publishFromPackage: publishFromPackage,
-  checkVersions: checkVersions,
+  publishManual: prepareAndPublish,
+  forcePublish: prepareAndForcePublish,
+  publishFromPackage: prepareAndPublishFromPackage,
+  checkVersions: prepareAndCheckVersions,
   testGhPagesBeta: testGhPagesLocally(true),
   testGhPages: testGhPagesLocally(false),
 };

scripts.md

@@ -52,55 +52,66 @@ This script builds all files needed to deploy plugins and examples to GitHub Pag
 
 This script installs a beta version of Blockly, builds all files needed to deploy plugins and examples to GitHub Pages, then starts a local server with that content.
 
+## Publishing scripts
+
+Note that publishing via the command line is not preferred. You should
+use the GitHub Action workflow whenever possible, which can handle
+publishing all plugins as well as recovering from the partially-published
+state (publishing unpublished plugins only).
+
+Note that none of these scripts will handle npm authentication. You need to
+configure an npm authentication token before you can use these scripts.
+
+Full publishing documentation can be found in the internal team documentation.
+
 ### `npm run publish:prepare`
 
 This script will clone a copy of blockly-samples to a directory called `dist`,
-run `npm ci`, build and test all plugins, and then log in to the npm publishing
-service. It must be run before any of the other manual publishing commands are
-run.
+run `npm ci`, then build and test all plugins.
 
 If any plugin fails to build or some tests fail, this script should fail. Since
 nothing has been pushed to npm or github, you can simply correct the error and
 try again.
 
+This script will be run automatically before any of the other publish scripts,
+so you do not need to run it manually first.
+
 ### `npm run publish:manual`
 
-This script assumes that you have already run `npm run publish:prepare`. It will
+This script will first run `npm run publish:prepare`. It will
 publish all of the changed plugins since the last release, using the `dist`
 directory. It runs the lerna command that uses conventional commits to determine
 a new version number for each plugin, and publishes the new versions to npm and
-to a github release and tag. Plugins do not automatically build themselves
-before publishing. You must have run `npm run publish:prepare` script ahead of
-time for this reason.
+to a github release and tag.
 
 If there is some error with npm while running this command, you may end up in a
 state where some plugins have been published to npm and not others, after lerna
 has already tagged the new releases. You can recover from this state by fixing
-the error, and then running `npm run publish:prepare` again followed by
+the error, and then running either
 `npm run publish:unpublishedOnly` or `npm run publish:force`.
 
 ### `npm run publish:unpublishedOnly`
 
-This script assumes that you have already run `npm run publish:prepare`. It uses the `dist`
+This script will first run `npm run publish:prepare`. It uses the `dist`
 directory created in that script. It uses lerna to check each plugin to see if the version
 in `package.json` matches the version on npm. If a version is not yet on npm, it will publish
 that plugin without updating its version number. Thus, this script should only be used
 after `lerna version` has been run in some form (most commonly, during a run of
 `npm run publish:manual` that subsequently failed).
 
-If this script fails, correct the error and re-run `npm run publish:prepare` and
+If this script fails, correct the error and re-run
 `npm run publish:unpublishedOnly`.
 
 ### `npm run publish:force`
 
-This script assumes you have already run `npm run publish:prepare`. It will use lerna
+This script will first run `npm run publish:prepare`. It will use lerna
 to force publish all packages, even those that have not changed. You can use this
 if you run into publishing problems to recover from error states, but you should prefer
 to use `npm run publish:unpublishedOnly` if possible.
 
 ### `npm run publish:checkVersions`
 
-This script assumes you have already run `npm run publish:prepare`. It will run `lerna
+This script will first run `npm run publish:prepare`. It will run `lerna
 version` to generate the new version numbers using conventional commits that would be
 created during a full publish action, but it will not actually push the changes nor
 create any tags. This can be used to check which plugins would be published and under