@wpelevator/wp-release 0.6.1 → 0.8.0

package/dist/changeset-release.js

@@ -6,7 +6,7 @@ import { promisify } from 'node:util';
 import { loadChangesetConfig } from "./changeset-config.js";
 import { findMainPluginFile } from "./package-meta.js";
 import { findConstantValues } from "./version-check.js";
-import { getChangesetBump, getNextVersion, parseChangeset, } from "./changesets.js";
+import { formatChangelogList, formatChangeset, getChangesetBump, getNextVersion, parseChangeset, } from "./changesets.js";
 import { ValidationError } from "./errors.js";
 const execFileAsync = promisify(execFile);
 /**
@@ -19,6 +19,18 @@ export async function getChangesetReleasePlan(input) {
     const context = await getReleaseContext(input);
     return context?.plan;
 }
+/**
+ * Discover the packages of the repository configuration.
+ *
+ * @param  input Repository root and optional explicit config file.
+ * @return Packages in the configured order with their current versions.
+ * @throws {ValidationError} Without a config, or for an invalid one.
+ */
+export async function getChangesetPackages(input) {
+    const loaded = await requireConfig(input);
+    const packages = await discoverPackages(input.cwd, loaded.config);
+    return packages.map(toChangesetPackage);
+}
 async function getReleaseContext(input) {
     const loaded = await loadChangesetConfig(input);
     if (!loaded) {
@@ -110,12 +122,17 @@ export async function versionChangesets(input) {
     if (!context) {
         throw new ValidationError('No wp-release config found. Add wp-release.config.js or pass --config <path>.');
     }
-    const { config, packages, plan: releasePlan } = context;
+    const { config, packages } = context;
+    const releasePlan = input.packages
+        ? selectReleasePlan(context.plan, packages, input.packages)
+        : context.plan;
     const date = input.date ?? new Date().toISOString().slice(0, 10);
+    const changesetDirectory = path.resolve(input.cwd, config.changesets ?? '.changeset');
+    const releases = await getVersionedReleases(input.cwd, config, releasePlan.releases, changesetDirectory);
     if (!input.dryRun) {
         const journal = new Map();
         try {
-            for (const release of releasePlan.releases) {
+            for (const release of releases) {
                 const configured = packages.find((pkg) => pkg.name === release.package.name);
                 if (!configured) {
                     throw new ValidationError(`Unknown package "${release.package.name}".`);
@@ -126,11 +143,8 @@ export async function versionChangesets(input) {
                 await verifyVersionTargets(input.cwd, configured, release.nextVersion);
                 await prependChangelog(configured.directory, release, date, config.readmeChangelog ?? false, config.changelogInsertAfter, journal);
             }
-            const changesetDirectory = path.resolve(input.cwd, config.changesets ?? '.changeset');
             for (const changeset of releasePlan.changesets) {
-                const file = path.join(changesetDirectory, changeset.fileName);
-                await rememberFile(journal, file);
-                await rm(file);
+                await consumeChangeset(path.join(changesetDirectory, changeset.fileName), changeset, input.packages, journal);
             }
         }
         catch (error) {
@@ -142,11 +156,118 @@ export async function versionChangesets(input) {
         }
     }
     return {
-        ...releasePlan,
+        changesets: releasePlan.changesets,
+        releases,
         date,
         changed: !input.dryRun && releasePlan.changesets.length > 0,
     };
 }
+/**
+ * Format the changelog entries of each release, with the configured
+ * formatter and the commit that added each changeset.
+ *
+ * @param cwd                Repository root.
+ * @param config             Repository release configuration.
+ * @param releases           Package releases.
+ * @param changesetDirectory Directory of the changeset files.
+ * @return Releases with their changelog entries.
+ */
+async function getVersionedReleases(cwd, config, releases, changesetDirectory) {
+    const commits = new Map();
+    const getCommit = (changeset) => {
+        const cached = commits.get(changeset.fileName) ??
+            getChangesetCommit(cwd, path.join(changesetDirectory, changeset.fileName));
+        commits.set(changeset.fileName, cached);
+        return cached;
+    };
+    return Promise.all(releases.map(async (release) => {
+        const entries = [];
+        // Format one at a time, so that formatters calling an API aren't rate limited.
+        for (const changeset of release.changesets) {
+            entries.push(await getChangelogEntry(config, release.package, changeset, getCommit));
+        }
+        return { ...release, changelog: formatChangelogList(entries) };
+    }));
+}
+async function getChangelogEntry(config, pkg, changeset, getCommit) {
+    const summary = changeset.summary.trim();
+    if (!summary || !config.changelogEntry) {
+        return summary;
+    }
+    const commit = await getCommit(changeset);
+    const entry = await config.changelogEntry({
+        package: pkg,
+        changeset,
+        ...(commit ? { commit } : {}),
+    });
+    if ('string' !== typeof entry) {
+        throw new ValidationError(`The changelogEntry formatter didn't return a string for changeset ${changeset.fileName}.`);
+    }
+    return entry.trim();
+}
+/**
+ * Find the commit that added a changeset file.
+ *
+ * @param cwd  Repository root.
+ * @param file Changeset file.
+ * @return Commit, or undefined when the file isn't committed.
+ */
+async function getChangesetCommit(cwd, file) {
+    const output = await git(cwd, [
+        'log',
+        '--diff-filter=A',
+        '--format=%H%x1f%h%x1f%s',
+        '-1',
+        '--',
+        path.relative(cwd, file).split(path.sep).join('/'),
+    ]);
+    const [hash, shortHash = '', subject = ''] = output
+        .trim()
+        .split('\x1f');
+    return hash ? { hash, shortHash, subject } : undefined;
+}
+/**
+ * Limit a release plan to some packages and the changesets that name them.
+ *
+ * @param  plan     Release plan of all pending changesets.
+ * @param  packages Configured packages.
+ * @param  names    Packages to version.
+ * @return Release plan of the named packages.
+ * @throws {ValidationError} For unknown packages.
+ */
+function selectReleasePlan(plan, packages, names) {
+    names.forEach((name) => {
+        if (!packages.some((pkg) => pkg.name === name)) {
+            throw new ValidationError(`Unknown package "${name}".`);
+        }
+    });
+    return {
+        releases: plan.releases.filter((release) => names.includes(release.package.name)),
+        changesets: plan.changesets.filter((changeset) => names.some((name) => Object.hasOwn(changeset.packages, name))),
+    };
+}
+/**
+ * Remove an applied changeset, or only the applied packages from a changeset
+ * that names other packages too, so that their releases keep its summary.
+ *
+ * @param file      Changeset file.
+ * @param changeset Parsed changeset.
+ * @param applied   Versioned packages, or undefined when all were versioned.
+ * @param journal   File journal for rolling back.
+ */
+async function consumeChangeset(file, changeset, applied, journal) {
+    const remaining = Object.entries(changeset.packages).filter(([name]) => undefined !== applied && !applied.includes(name));
+    await rememberFile(journal, file);
+    if (remaining.length) {
+        await writeFile(file, formatChangeset({
+            packages: Object.fromEntries(remaining),
+            summary: changeset.summary,
+        }));
+    }
+    else {
+        await rm(file);
+    }
+}
 /**
  * Create missing release tags, optionally pushing them to the configured remote.
  *
@@ -164,19 +285,26 @@ export async function tagChangesets(input) {
     if (!context) {
         throw new ValidationError('No wp-release config found. Add wp-release.config.js or pass --config <path>.');
     }
+    const selected = selectPackages(context.packages, input);
     const packages = input.since
-        ? (await changedPackagesSince(input.cwd, context.packages, input.since)).packages
-        : context.packages;
+        ? (await changedPackagesSince(input.cwd, selected, input.since))
+            .packages
+        : selected;
     const results = [];
     const dryRun = input.dryRun || input.untagged;
     const tagFormat = context.config.tagFormat ?? '{path}/{version}';
     for (const pkg of packages) {
-        const version = 'git-tag' === pkg.versionConfig.from.kind
-            ? await getLatestChangelogVersion(pkg.directory, pkg.currentVersion)
-            : pkg.currentVersion;
+        const version = await getTagVersion(pkg, input.version);
+        if (undefined !== input.version && input.version !== version) {
+            throw new ValidationError(`Package "${pkg.name}" is at version ${version}, not ${input.version}.`);
+        }
         const tag = formatTag(tagFormat, pkg, version);
         const exists = await gitTagExists(input.cwd, tag);
-        const notes = await readReleaseNotes(pkg.directory, version);
+        if (!exists) {
+            await verifyVersionTargets(input.cwd, pkg, version);
+        }
+        const previousTag = await getPreviousTag(input.cwd, formatTag(tagFormat, pkg, ''), version);
+        const notes = await getReleaseNotes(input.cwd, context.config, pkg, { version, tag, previousTag }, exists ? tag : 'HEAD');
         if (!exists && !dryRun) {
             await git(input.cwd, ['tag', tag]);
         }
@@ -184,6 +312,8 @@ export async function tagChangesets(input) {
             package: pkg.name,
             version,
             tag,
+            ...(previousTag ? { previousTag } : {}),
+            prerelease: isPrerelease(version),
             exists,
             created: !exists && !dryRun,
             notes,
@@ -223,6 +353,7 @@ async function createGitHubRelease(cwd, release) {
                 `${release.package}@${release.version}`,
                 '--notes',
                 release.notes,
+                ...(release.prerelease ? ['--prerelease'] : []),
             ], { cwd });
         }
         catch (error) {
@@ -231,6 +362,141 @@ async function createGitHubRelease(cwd, release) {
         }
     }
 }
+/**
+ * Get the version to tag. Packages versioned by their git tags have no
+ * version file, so the expected version is the version to tag, or else the
+ * latest CHANGELOG.md version.
+ *
+ * @param pkg      Configured package.
+ * @param expected Expected version from --version, if any.
+ * @return Version to tag.
+ */
+async function getTagVersion(pkg, expected) {
+    if ('git-tag' !== pkg.versionConfig.from.kind) {
+        return pkg.currentVersion;
+    }
+    return (expected ??
+        (await getLatestChangelogVersion(pkg.directory, pkg.currentVersion)));
+}
+/**
+ * Pick the packages passed with --package, or all packages without it.
+ *
+ * @param  packages Configured packages.
+ * @param  input    Tag options.
+ * @return Selected packages in the configured order.
+ * @throws {ValidationError} For unknown packages, or --version without a single package.
+ */
+function selectPackages(packages, input) {
+    const names = input.packages ?? [];
+    if (undefined !== input.version && 1 !== names.length) {
+        throw new ValidationError('An expected version requires exactly one package.');
+    }
+    names.forEach((name) => {
+        if (!packages.some((pkg) => pkg.name === name)) {
+            throw new ValidationError(`Unknown package "${name}".`);
+        }
+    });
+    return names.length
+        ? packages.filter((pkg) => names.includes(pkg.name))
+        : packages;
+}
+/**
+ * Find the tag of the newest release before a version.
+ *
+ * @param cwd     Repository root.
+ * @param prefix  Tag prefix of the package, like `plugins/alpha/`.
+ * @param version Version being released.
+ * @return Previous tag, or undefined for the first release.
+ */
+async function getPreviousTag(cwd, prefix, version) {
+    const output = await git(cwd, ['tag', '--list', `${prefix}*`]);
+    return output
+        .trim()
+        .split(/\r?\n/)
+        .filter((tag) => tag.startsWith(prefix))
+        .map((tag) => ({ tag, version: tag.slice(prefix.length) }))
+        .filter((item) => isVersion(item.version) &&
+        compareVersions(item.version, version) < 0)
+        .sort((a, b) => compareVersions(b.version, a.version))[0]?.tag;
+}
+/**
+ * Build the release notes of a tag with the configured formatter.
+ *
+ * @param cwd                 Repository root.
+ * @param config              Repository release configuration.
+ * @param pkg                 Released package.
+ * @param release             Version, tag and previous tag of the release.
+ * @param release.version     Released version.
+ * @param release.tag         Release tag.
+ * @param release.previousTag Tag of the previous release, if any.
+ * @param end                 Commit of the release: the tag, or HEAD before tagging.
+ * @return Release notes.
+ */
+async function getReleaseNotes(cwd, config, pkg, release, end) {
+    const changelog = await readReleaseNotes(pkg.directory, release.version);
+    const commits = await getReleaseCommits(cwd, pkg, end, release.previousTag);
+    const notes = changelog ||
+        commits
+            .map((commit) => `- ${commit.subject} (${commit.shortHash})`)
+            .join('\n');
+    if (!config.releaseNotes) {
+        return notes;
+    }
+    const formatted = await config.releaseNotes({
+        package: toChangesetPackage(pkg),
+        ...release,
+        changelog,
+        commits,
+        notes,
+    });
+    if ('string' !== typeof formatted) {
+        throw new ValidationError(`The releaseNotes formatter didn't return a string for package "${pkg.name}".`);
+    }
+    return formatted.trim();
+}
+/**
+ * List the commits that changed a package since its previous release.
+ *
+ * @param cwd         Repository root.
+ * @param pkg         Released package.
+ * @param end         Commit of the release.
+ * @param previousTag Tag of the previous release, if any.
+ * @return Commits, newest first.
+ */
+async function getReleaseCommits(cwd, pkg, end, previousTag) {
+    const packageFromRepo = path.relative(cwd, pkg.directory).split(path.sep).join('/') ||
+        '.';
+    const output = await git(cwd, [
+        'log',
+        '--format=%H%x1f%h%x1f%s',
+        previousTag ? `${previousTag}..${end}` : end,
+        '--',
+        packageFromRepo,
+    ]);
+    return output
+        .trim()
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .map((line) => {
+        const [hash = '', shortHash = '', subject = ''] = line.split('\x1f');
+        return { hash, shortHash, subject };
+    });
+}
+/**
+ * Remove the release configuration from a package passed to config callbacks.
+ *
+ * @param pkg Configured package.
+ * @return Package without its group configuration.
+ */
+function toChangesetPackage(pkg) {
+    return {
+        name: pkg.name,
+        directory: pkg.directory,
+        path: pkg.path,
+        type: pkg.type,
+        currentVersion: pkg.currentVersion,
+    };
+}
 /**
  * Check whether changed files belong to packages without a changeset.
  *
@@ -549,9 +815,7 @@ async function prependChangelog(directory, release, date, readmeChangelog, chang
     const summaries = release.changesets
         .map((item) => item.summary.trim())
         .filter(Boolean);
-    const section = `## ${release.nextVersion} (${date})\n\n${summaries
-        .map((item) => `- ${item.replaceAll(/\r?\n/g, '\n  ')}`)
-        .join('\n')}\n\n`;
+    const section = `## ${release.nextVersion} (${date})\n\n${release.changelog}\n\n`;
     const changelog = path.join(directory, 'CHANGELOG.md');
     let previous = '';
     try {
@@ -826,10 +1090,60 @@ function packageType(group) {
     }
     return 'other';
 }
+const VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?$/;
+function isVersion(version) {
+    return VERSION_PATTERN.test(version);
+}
+function isPrerelease(version) {
+    return Boolean(VERSION_PATTERN.exec(version)?.[4]);
+}
+/**
+ * Compare two versions with SemVer precedence, where a pre-release like
+ * 1.0.0-rc.1 comes before 1.0.0.
+ *
+ * @param left  Version.
+ * @param right Version to compare with.
+ * @return Negative when left is lower, positive when higher, otherwise 0.
+ */
 function compareVersions(left, right) {
-    const a = left.split('.').map(Number);
-    const b = right.split('.').map(Number);
-    return ((a[0] ?? 0) - (b[0] ?? 0) ||
+    const [leftCore = '', leftPre] = splitPrerelease(left);
+    const [rightCore = '', rightPre] = splitPrerelease(right);
+    const a = leftCore.split('.').map(Number);
+    const b = rightCore.split('.').map(Number);
+    const core = (a[0] ?? 0) - (b[0] ?? 0) ||
         (a[1] ?? 0) - (b[1] ?? 0) ||
-        (a[2] ?? 0) - (b[2] ?? 0));
+        (a[2] ?? 0) - (b[2] ?? 0);
+    if (core || leftPre === rightPre) {
+        return core;
+    }
+    if (undefined === leftPre || undefined === rightPre) {
+        return undefined === leftPre ? 1 : -1;
+    }
+    return comparePrerelease(leftPre.split('.'), rightPre.split('.'));
+}
+function splitPrerelease(version) {
+    const index = version.indexOf('-');
+    return -1 === index
+        ? [version]
+        : [version.slice(0, index), version.slice(index + 1)];
+}
+function comparePrerelease(left, right) {
+    const [a, ...leftRest] = left;
+    const [b, ...rightRest] = right;
+    if (undefined === a || undefined === b) {
+        return (undefined === a ? 0 : 1) - (undefined === b ? 0 : 1);
+    }
+    const order = compareIdentifier(a, b);
+    return order || comparePrerelease(leftRest, rightRest);
+}
+function compareIdentifier(a, b) {
+    const aNumeric = /^\d+$/.test(a);
+    const bNumeric = /^\d+$/.test(b);
+    if (aNumeric && bNumeric) {
+        return Number(a) - Number(b);
+    }
+    if (aNumeric || bNumeric) {
+        return aNumeric ? -1 : 1;
+    }
+    return Number(a > b) - Number(a < b);
 }

package/dist/changesets.d.ts

@@ -32,6 +32,11 @@ export interface PackageRelease {
     nextVersion: string;
     changesets: Changeset[];
 }
+/** A package release with its formatted changelog entries, once versioned. */
+export interface VersionedRelease extends PackageRelease {
+    /** Changelog entries as a Markdown list, as added to CHANGELOG.md. */
+    changelog: string;
+}
 /** Deterministic release plan assembled from pending changesets. */
 export interface ChangesetReleasePlan {
     changesets: Changeset[];
@@ -53,6 +58,20 @@ export declare function parseChangeset(contents: string, fileName?: string): Cha
  * @return Markdown contents with a trailing newline.
  */
 export declare function formatChangeset(changeset: Omit<Changeset, 'fileName'>): string;
+/**
+ * Format the summaries of changesets as a Markdown list of changelog entries.
+ *
+ * @param changesets Changesets of a release.
+ * @return Markdown list, empty without summaries.
+ */
+export declare function formatChangelogEntries(changesets: Changeset[]): string;
+/**
+ * Format changelog entries as a Markdown list, indenting their extra lines.
+ *
+ * @param entries Changelog entries; empty ones are left out.
+ * @return Markdown list, empty without entries.
+ */
+export declare function formatChangelogList(entries: string[]): string;
 /**
  * Return the strongest bump requested for a package across changesets.
  *

package/dist/changesets.js

@@ -64,6 +64,27 @@ export function formatChangeset(changeset) {
         .join('\n');
     return `---\n${frontmatter}\n---\n\n${changeset.summary.trim()}\n`;
 }
+/**
+ * Format the summaries of changesets as a Markdown list of changelog entries.
+ *
+ * @param changesets Changesets of a release.
+ * @return Markdown list, empty without summaries.
+ */
+export function formatChangelogEntries(changesets) {
+    return formatChangelogList(changesets.map((item) => item.summary.trim()));
+}
+/**
+ * Format changelog entries as a Markdown list, indenting their extra lines.
+ *
+ * @param entries Changelog entries; empty ones are left out.
+ * @return Markdown list, empty without entries.
+ */
+export function formatChangelogList(entries) {
+    return entries
+        .filter(Boolean)
+        .map((item) => `- ${item.replaceAll(/\r?\n/g, '\n  ')}`)
+        .join('\n');
+}
 /**
  * Return the strongest bump requested for a package across changesets.
  *

package/dist/cli.js

@@ -6,6 +6,7 @@ import sign from "./commands/sign.js";
 import verify from "./commands/verify.js";
 import versionCheck from "./commands/version-check.js";
 import deploySvn from "./commands/deploy-svn.js";
+import deployGit from "./commands/deploy-git.js";
 import { Logger, TextWriter } from "./logger.js";
 import { getBoolean, getString } from "./commands/command.js";
 import { ValidationError } from "./errors.js";
@@ -25,6 +26,7 @@ export const commands = [
     verify,
     versionCheck,
     deploySvn,
+    deployGit,
     changesetAdd,
     changesetStatus,
     changesetVersion,

package/dist/commands/changeset-args.d.ts

@@ -61,11 +61,16 @@ export declare const changesetVersionArgs: {
     readonly date: {
         readonly type: "string";
     };
+    readonly package: {
+        readonly type: "string";
+        readonly multiple: true;
+    };
 };
 /** Parsed input for `changeset-version`. */
 export interface ChangesetVersionArgs {
     dryRun: boolean;
     date?: string;
+    packages?: string[];
 }
 /**
  * Validate and normalize a release date option.
@@ -100,6 +105,13 @@ export declare const changesetTagArgs: {
     readonly since: {
         readonly type: "string";
     };
+    readonly package: {
+        readonly type: "string";
+        readonly multiple: true;
+    };
+    readonly version: {
+        readonly type: "string";
+    };
 };
 /** Parsed input for `changeset-tag`. */
 export interface ChangesetTagArgs {
@@ -108,6 +120,8 @@ export interface ChangesetTagArgs {
     untagged: boolean;
     githubRelease: boolean;
     since?: string;
+    packages: string[];
+    version?: string;
 }
 /**
  * Parse the `changeset-tag` options.

package/dist/commands/changeset-args.js

@@ -74,6 +74,7 @@ export function parseChangesetStatusArgs(values) {
 export const changesetVersionArgs = {
     'dry-run': { type: 'boolean' },
     date: { type: 'string' },
+    package: { type: 'string', multiple: true },
 };
 /**
  * Validate and normalize a release date option.
@@ -104,9 +105,14 @@ export function parseChangesetDate(value) {
  */
 export function parseChangesetVersionArgs(values) {
     const date = parseChangesetDate(getString(values, 'date'));
+    const packages = getStrings(values, 'package');
+    if (packages.some((name) => !name.trim())) {
+        throw new ValidationError('--package <name> must not be empty.');
+    }
     return {
         dryRun: getBoolean(values, 'dry-run'),
         ...(date ? { date } : {}),
+        ...(packages.length ? { packages } : {}),
     };
 }
 /** Parse-args options for `changeset-tag`. */
@@ -116,6 +122,8 @@ export const changesetTagArgs = {
     untagged: { type: 'boolean' },
     'github-release': { type: 'boolean' },
     since: { type: 'string' },
+    package: { type: 'string', multiple: true },
+    version: { type: 'string' },
 };
 /**
  * Parse the `changeset-tag` options.
@@ -130,10 +138,21 @@ export function parseChangesetTagArgs(values) {
         untagged: getBoolean(values, 'untagged'),
         githubRelease: getBoolean(values, 'github-release'),
         since: getString(values, 'since'),
+        packages: getStrings(values, 'package'),
+        version: getString(values, 'version')?.trim(),
     };
     if ('' === args.since?.trim()) {
         throw new ValidationError('--since <ref> must not be empty.');
     }
+    if (args.packages.some((name) => !name.trim())) {
+        throw new ValidationError('--package <name> must not be empty.');
+    }
+    if ('' === args.version) {
+        throw new ValidationError('--version <version> must not be empty.');
+    }
+    if (undefined !== args.version && 1 !== args.packages.length) {
+        throw new ValidationError('--version <version> requires exactly one --package <name>.');
+    }
     if (args.githubRelease && !args.push) {
         throw new ValidationError('--github-release requires --push.');
     }

package/dist/commands/changeset-tag.d.ts

@@ -19,6 +19,13 @@ declare const _default: {
         readonly since: {
             readonly type: "string";
         };
+        readonly package: {
+            readonly type: "string";
+            readonly multiple: true;
+        };
+        readonly version: {
+            readonly type: "string";
+        };
     };
     run({ values, cwd, configFile, logger }: import("./command.ts").CommandContext): Promise<{
         exitCode: number;

package/dist/commands/changeset-tag.js

@@ -1,18 +1,25 @@
 import { tagChangesets } from "../changeset-release.js";
 import { parseChangesetTagArgs, changesetTagArgs } from "./changeset-args.js";
+import { getChangesetTagSummary, getTagStatus } from "../summary.js";
 export default {
     name: 'changeset-tag',
-    usage: 'changeset-tag [--dry-run] [--untagged] [--since <ref>] [--push] [--github-release]',
+    usage: 'changeset-tag [--dry-run] [--untagged] [--since <ref>] [--package <name>] [--version <version>] [--push] [--github-release]',
     summary: 'Create missing release tags for configured package versions.',
     help: `Options:
-  --dry-run              List missing tags without creating them
+  --dry-run              List missing tags and their release notes without
+                         creating them
   --untagged             List only releases without a tag, without creating tags
   --since <ref>          Tag packages changed since this git ref
+  --package <name>       Tag only this package (repeatable)
+  --version <version>    Fail unless the single --package is at this version;
+                         the version to tag for packages versioned by git tags
   --push                 Push newly created tags to origin
-  --github-release       Create a GitHub Release for each tag
+  --github-release       Create a GitHub Release for each tag, marked as a
+                         pre-release for versions like 1.0.0-rc.1
 
 Tags are created only when absent, and GitHub Releases are created only when
-missing, so rerunning after a partial failure is safe. --github-release also
+missing, so rerunning after a partial failure is safe. Before a tag is created,
+every configured version target must match the version. --github-release also
 requires --push. With --json or --github-output, --untagged lists the releases
 that still need a tag, for example to release each of them with a separate
 workflow.`,
@@ -24,7 +31,17 @@ workflow.`,
             ...(configFile ? { configFile } : {}),
             ...args,
         });
-        result.tags.forEach((item) => logger.info(`${item.created ? 'Created' : 'Exists'} ${item.tag}`));
+        result.tags.forEach((item) => {
+            logger.info(`${getTagStatus(item)} ${item.tag}`);
+            // A dry run is for previewing the release notes.
+            if (args.dryRun) {
+                logger.info(item.notes || 'No release notes.');
+            }
+            else {
+                logger.debug(item.notes);
+            }
+        });
+        logger.summary(() => getChangesetTagSummary(result));
         return { exitCode: 0, result };
     },
 };