Don't recommend initial use of intentionally-skip (#119)

Currently we say in the releas spec that if the user wants to skip a
package, they can specify "intentionally-skip" in place of the version.
We actually don't want first-time users to know about this directive up
front, because it suppresses errors that would ordinarily be produced if
you omit a package from the release that you shouldn't. Rather, we want
to only suggest this in the error message.

Hence, this commit removes the reference to "intentionally-skip" from
the release spec. It also adds some more instructions for first-time
users.

src/release-specification.test.ts

@@ -45,23 +45,38 @@ describe('release-specification', () => {
 
       expect(template).toStrictEqual(
         `
-# The following is a list of packages in monorepo.
-# Please indicate the packages for which you want to create a new release
-# by updating "null" to one of the following:
+# This file (called the "release spec") allows you to specify which packages you
+# want to include in this release along with the new versions they should
+# receive.
+#
+# By default, all packages which have changed since their latest release are
+# listed here. You can choose not to publish a package by removing it from this
+# list.
+#
+# For each package you *do* want to release, you will need to specify how that
+# version should be changed depending on the impact of the changes that will go
+# into the release. To help you make this decision, all of the changes have been
+# automatically added to the changelog for the package. This has been done
+# in a new commit, so you can keep this file open, run \`git show\` in the
+# terminal, review the set of changes, then return to this file to specify the
+# version.
+#
+# A version specifier (the value that goes after each package in the list below)
+# can be one of the following:
 #
 # - "major" (if you want to bump the major part of the package's version)
 # - "minor" (if you want to bump the minor part of the package's version)
 # - "patch" (if you want to bump the patch part of the package's version)
 # - an exact version with major, minor, and patch parts (e.g. "1.2.3")
-# - intentionally-skip (to skip the package entirely)
 #
-# When you're finished making your selections, save this file and
-# create-release-branch will continue automatically.
+# When you're finished, save this file and close it. The tool will update the
+# versions of the packages you've listed and will move the changelog entries to
+# a new section.
 
 packages:
   a: null
   c: null
-`.slice(1),
+`.trimStart(),
       );
     });
 
@@ -108,23 +123,38 @@ packages:
 
       expect(template).toStrictEqual(
         `
-# The following is a list of packages in monorepo.
-# Please indicate the packages for which you want to create a new release
-# by updating "null" to one of the following:
+# This file (called the "release spec") allows you to specify which packages you
+# want to include in this release along with the new versions they should
+# receive.
+#
+# By default, all packages which have changed since their latest release are
+# listed here. You can choose not to publish a package by removing it from this
+# list.
+#
+# For each package you *do* want to release, you will need to specify how that
+# version should be changed depending on the impact of the changes that will go
+# into the release. To help you make this decision, all of the changes have been
+# automatically added to the changelog for the package. This has been done
+# in a new commit, so you can keep this file open, run \`git show\` in the
+# terminal, review the set of changes, then return to this file to specify the
+# version.
+#
+# A version specifier (the value that goes after each package in the list below)
+# can be one of the following:
 #
 # - "major" (if you want to bump the major part of the package's version)
 # - "minor" (if you want to bump the minor part of the package's version)
 # - "patch" (if you want to bump the patch part of the package's version)
 # - an exact version with major, minor, and patch parts (e.g. "1.2.3")
-# - intentionally-skip (to skip the package entirely)
 #
-# When you're finished making your selections, save this file and then re-run
-# create-release-branch.
+# When you're finished, save this file and then run create-release-branch again.
+# The tool will update the versions of the packages you've listed and will move
+# the changelog entries to a new section.
 
 packages:
   a: null
   b: null
-`.slice(1),
+`.trimStart(),
       );
     });
   });

src/release-specification.ts

@@ -55,30 +55,46 @@ const INTENTIONALLY_SKIP_PACKAGE_DIRECTIVE = 'intentionally-skip';
  * @returns The release specification template.
  */
 export async function generateReleaseSpecificationTemplateForMonorepo({
-  project: { rootPackage, workspacePackages },
+  project: { workspacePackages },
   isEditorAvailable,
 }: {
   project: Project;
   isEditorAvailable: boolean;
 }) {
   const afterEditingInstructions = isEditorAvailable
     ? `
-# When you're finished making your selections, save this file and
-# create-release-branch will continue automatically.`.trim()
+# When you're finished, save this file and close it. The tool will update the
+# versions of the packages you've listed and will move the changelog entries to
+# a new section.`.trim()
     : `
-# When you're finished making your selections, save this file and then re-run
-# create-release-branch.`.trim();
+# When you're finished, save this file and then run create-release-branch again.
+# The tool will update the versions of the packages you've listed and will move
+# the changelog entries to a new section.`.trim();
 
   const instructions = `
-# The following is a list of packages in ${rootPackage.validatedManifest.name}.
-# Please indicate the packages for which you want to create a new release
-# by updating "null" to one of the following:
+# This file (called the "release spec") allows you to specify which packages you
+# want to include in this release along with the new versions they should
+# receive.
+#
+# By default, all packages which have changed since their latest release are
+# listed here. You can choose not to publish a package by removing it from this
+# list.
+#
+# For each package you *do* want to release, you will need to specify how that
+# version should be changed depending on the impact of the changes that will go
+# into the release. To help you make this decision, all of the changes have been
+# automatically added to the changelog for the package. This has been done
+# in a new commit, so you can keep this file open, run \`git show\` in the
+# terminal, review the set of changes, then return to this file to specify the
+# version.
+#
+# A version specifier (the value that goes after each package in the list below)
+# can be one of the following:
 #
 # - "major" (if you want to bump the major part of the package's version)
 # - "minor" (if you want to bump the minor part of the package's version)
 # - "patch" (if you want to bump the patch part of the package's version)
 # - an exact version with major, minor, and patch parts (e.g. "1.2.3")
-# - intentionally-skip (to skip the package entirely)
 #
 ${afterEditingInstructions}
   `.trim();