From ce9f4c0b6936862b788c6ea817545c792c1cceb2 Mon Sep 17 00:00:00 2001 From: Elliot Winkler Date: Tue, 5 Dec 2023 14:31:28 -0700 Subject: [PATCH] Don't recommend initial use of intentionally-skip 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 | 58 +++++++++++++++++++++++-------- src/release-specification.ts | 34 +++++++++++++----- 2 files changed, 69 insertions(+), 23 deletions(-) diff --git a/src/release-specification.test.ts b/src/release-specification.test.ts index 1be176c..54f60c6 100644 --- a/src/release-specification.test.ts +++ b/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(), ); }); }); diff --git a/src/release-specification.ts b/src/release-specification.ts index d73a0b8..681d61b 100644 --- a/src/release-specification.ts +++ b/src/release-specification.ts @@ -55,7 +55,7 @@ const INTENTIONALLY_SKIP_PACKAGE_DIRECTIVE = 'intentionally-skip'; * @returns The release specification template. */ export async function generateReleaseSpecificationTemplateForMonorepo({ - project: { rootPackage, workspacePackages }, + project: { workspacePackages }, isEditorAvailable, }: { project: Project; @@ -63,22 +63,38 @@ export async function generateReleaseSpecificationTemplateForMonorepo({ }) { 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();