@wpelevator/wp-release 0.6.1 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # WP Release
 
-Package, checksum, verify and version-check WordPress plugins and themes, and deploy plugins to the WordPress.org plugin SVN repository. Usable as a CLI, as a library, and through the [`wp-release-zip`](https://github.com/wpelevator/wp-release-zip), [`wp-release-checksums`](https://github.com/wpelevator/wp-release-checksums), [`wp-release-sign`](https://github.com/wpelevator/wp-release-sign) and [`wp-release-deploy-svn`](https://github.com/wpelevator/wp-release-deploy-svn) GitHub Actions.
+Package, checksum, verify and version-check WordPress plugins and themes, deploy plugins to the WordPress.org plugin SVN repository, and deploy plugins, themes and packages to Git repositories. Usable as a CLI, as a library, and through the [`wp-release-zip`](https://github.com/wpelevator/wp-release-zip), [`wp-release-checksums`](https://github.com/wpelevator/wp-release-checksums), [`wp-release-sign`](https://github.com/wpelevator/wp-release-sign) and [`wp-release-deploy-svn`](https://github.com/wpelevator/wp-release-deploy-svn) GitHub Actions.
 
 Themes are released by uploading a ZIP on WordPress.org, so `deploy-svn` is for plugins only; use `zip` to build the theme upload.
 
@@ -32,6 +32,7 @@ npx wp-release --help
 | `wp-release verify [<source-dir>] --checksums <file> [options]` | Check a plugin or theme directory, or a ZIP, against a checksums manifest. |
 | `wp-release version-check [<source-dir>] [options]` | Check that the `Version` header, readme `Stable tag`, PHP constants and git tag agree. |
 | `wp-release deploy-svn [<source-dir>] [options]` | Deploy a plugin to the WordPress.org plugin SVN repository. |
+| `wp-release deploy-git [<source-dir>] --git-url <url> [options]` | Deploy the files of a plugin, theme or package to a Git repository as a release commit. |
 | `wp-release changeset-add [options]` | Record the release impact of a pull request. |
 | `wp-release changeset-status [options]` | List pending releases and check changed packages for changesets. |
 | `wp-release changeset-version [options]` | Apply version bumps and changelog entries. |
@@ -60,11 +61,14 @@ Each command also adds a section to the [job summary](https://docs.github.com/en
 | Command | Summary |
 |---|---|
 | `deploy-svn` | Plugin, linked to its WordPress.org page, version, written SVN paths, the commit linked to its WordPress.org changeset (or the dry run or no-op result), and the SVN changes in a collapsed table. |
+| `deploy-git` | Repository, release commit and the pushed branch and tag. |
 | `zip` | ZIP, number of files and checksums manifest. |
 | `checksums` | Manifest and number of files. |
 | `sign` | Signature files and the public key. |
 | `verify` | That all files match, or the counts and a table of the changed, missing and extra files. |
 | `version-check` | The matching version, or a table of the mismatches with their files and lines. |
+| `changeset-version` | A table of the package releases with their version changes and bumps. |
+| `changeset-tag` | Each tag with its previous tag and status, and its release notes in a collapsed section. |
 
 A failed command adds its error to the summary, or a table of its problems with their files and lines, listing up to 100 and counting the rest. The Markdown of the summaries isn't part of the library API. File paths are relative to `GITHUB_WORKSPACE`, or the current directory without it. Files outside it, like those of an extracted ZIP, get an annotation without a file. Multi-line messages stay one annotation.
 
@@ -89,8 +93,8 @@ flowchart TD
 	F -->|Pass| H["Merge the feature pull request to main"]
 	H --> I["changeset-version updates configured version files and changelogs"]
 	I --> J{"Are there package releases to review?"}
-	J -->|Yes| K["Workflow opens or updates the Version Packages pull request"]
-	K --> L["Review and merge the Version Packages pull request"]
+	J -->|Yes| K["Workflow opens or updates the release pull request"]
+	K --> L["Review and merge the release pull request"]
 	L --> M["changeset-tag creates tags for packages changed by that release"]
 	M --> N["GitHub Releases are created from changelog entries"]
 	N --> O["Tag-triggered publish and split workflows run"]
@@ -127,9 +131,17 @@ Add release notes in a feature PR with `npx wp-release changeset-add --package @
 
 On the release branch, preview with `changeset-version --dry-run`, then run `changeset-version` to update version targets and changelogs. By default, new Markdown entries go before the first version heading; `changelogInsertAfter` sets a literal insertion marker for `CHANGELOG.md` and, with `readmeChangelog`, the plugin readme. Put the marker in both files; a missing marker is an error. Without a marker, plugin readmes use the `== Changelog ==` heading. Failed updates are rolled back for safe retries.
 
+To release packages separately, for example with a release pull request for each, pass `--package <name>`, repeatable, to version only those packages. A changeset that also names other packages keeps only their entries and its summary, so it still applies to their releases with the same bump. Changesets without packages are left for a run without `--package`.
+
+The `changeset-version` result lists each release with its `package`, `bump`, `currentVersion`, `nextVersion` and `changelog` entries, a Markdown list like the one added to `CHANGELOG.md`. Use it to name and describe the release pull request in a repository script, or call `versionChangesets()` from the library and format the entries of each release with `formatChangelogEntries( release.changesets )`.
+
 After merging the release PR, `changeset-tag --since <merge-commit>^1 --push` pushes tags only for packages changed by that release. It pushes one tag at a time because GitHub doesn't trigger workflows for a push of more than three tags. Add `--github-release` to create missing GitHub Releases; it requires `--push`. For initial adoption, preview all missing tags with `changeset-tag --dry-run` (without `--since`), then push if needed. To release each package with a separate workflow instead, `changeset-tag --since <merge-commit>^1 --untagged --github-output` lists the releases that don't have a tag yet, without creating any. Tag pushes need Git write credentials; GitHub Releases need authenticated `gh`.
 
-For local development, run the TypeScript source with `npm run wp-release -- <command>` (for example, `npm run wp-release -- changeset-status --since origin/main`). GitHub workflows use the same CLI for versioning and tagging. `SUBTREE_DEPLOY_TOKEN` lets them update the Version Packages PR, push tags, and create GitHub Releases.
+To release a single package, for example from a manual workflow, pass `--package <name>`, repeatable, and with one package `--version <version>` to fail unless the package is at that version. Packages versioned by git tags have no version file, so for them `--version` is the version to tag. Before a tag is created, every `version.to` target must match the version, so a plugin `Version` header that disagrees with its readme `Stable tag` blocks the tag. GitHub Releases of versions with a pre-release part, like `1.0.0-rc.1`, are marked as pre-releases.
+
+The release notes are the version's `CHANGELOG.md` section, or without one the commits that changed the package since its previous tag, the highest version below the released one. Configure `releaseNotes( { package, version, tag, previousTag, changelog, commits, notes } )` to format them, for example to add links; `notes` is the default text and `commits` lists `{ hash, shortHash, subject }`, newest first. `changeset-tag --package <name> --dry-run` prints them without creating the tag.
+
+For local development, run the TypeScript source with `npm run wp-release -- <command>` (for example, `npm run wp-release -- changeset-status --since origin/main`). GitHub workflows use the same CLI for versioning and tagging. `SUBTREE_DEPLOY_TOKEN` lets them update the release PR, push tags, and create GitHub Releases.
 
 ### Naming convention
 
@@ -143,6 +155,7 @@ For local development, run the TypeScript source with `npm run wp-release -- <co
 | Verify files against a manifest | `wp-release verify` | |
 | Check that the versions agree | `wp-release version-check` | |
 | Deploy to WordPress.org SVN | `wp-release deploy-svn` | [`wpelevator/wp-release-deploy-svn`](https://github.com/wpelevator/wp-release-deploy-svn) |
+| Deploy to a Git repository | `wp-release deploy-git` | |
 
 Each concept has one name, written in the syntax of each interface:
 
@@ -154,11 +167,14 @@ Each concept has one name, written in the syntax of each interface:
 | Git tag to compare | `--git-tag <tag>` | | `gitTag` | Git tag checked by `version-check`. |
 | SVN tag to create | `--svn-tag <version>` | `svn-tag` | `svnTag` | Tag written by `deploy-svn`, distinct from a git tag. |
 | SVN repository | `--svn-url <url>` | `svn-url` | `svnUrl` | Deploy destination. |
+| Git repository | `--git-url <url>` | | `gitUrl` | Destination of `deploy-git`. Credentials come from git, like a token in the URL or an SSH key, and are never printed. |
+| Branch and tag to release to | `--branch <name>`, `--tag <name>` | | `branch`, `tag` | Refs written by `deploy-git` in the Git repository, distinct from the git tag that `version-check` compares. |
+| Source history | `--split-prefix <dir>` | | `splitPrefix` | Directory of a monorepo package whose history, from `git subtree split`, becomes the source history of `deploy-git` releases. |
 | SVN credentials | `--svn-username <name>`, `SVN_USERNAME` and `SVN_PASSWORD` env vars | `svn-username`, `svn-password` | `svnUsername`, `svnPassword` | Needed only to commit. There's no password flag, since it would show in the process list; the action inputs and library options fall back to the env vars. |
 | Log format | `--log-format <text\|github>`, `--ci` for `github` | always `github` | `writer: new TextWriter()` or `new GitHubActionsWriter()` | How the log is printed: plain text, or GitHub Actions annotations and job summaries. Each name matches the start of its writer class. |
 | Assets sync | `--no-assets` to skip | `assets: false` to skip | `assets` | Booleans are positive in the library and the action; `--no-assets` is only the CLI negation, never `noAssets` or a `no-assets` input. |
 
-CLI JSON results use camelCase keys like `zipPath`, and GitHub Action outputs use kebab-case like `zip-path`. Library classes are named after the capability (`SvnDeploy`, `Svn`) without repeating "release".
+CLI JSON results use camelCase keys like `zipPath`, and GitHub Action outputs use kebab-case like `zip-path`. Library classes are named after the capability (`SvnDeploy`, `Svn`, `GitDeploy`) without repeating "release".
 
 ### File selection
 
@@ -347,13 +363,43 @@ Validation:
 - `--trunk` without `--svn-tag` works but warns, because trunk then differs from the stable tag that WordPress.org serves downloads from.
 - A version mismatch throws a `VersionMismatchError`, a `ValidationError` with the `mismatches` and a problem for each, with its file and line. See [Logging](#logging).
 
+### Deploy to Git
+
+`deploy-git` deploys the selected files of a plugin, theme or package to a Git repository, like a distribution repository that ships the built files and `vendor/` for Composer installs or GitHub-hosted updates, or the release repository of a monorepo package. It selects files like `zip`, with `.distignore` and `--exclude`, so built files that git ignores in the source repository, like `build/` or `vendor/`, are released too. The source directory must be inside a Git repository, which provides the source history and stores the release objects before they're pushed.
+
+| Flag | Default | Writes |
+|---|---|---|
+| `--branch <name>` | off | Push the release to this branch |
+| `--tag <name>` | off | Create this tag for the release |
+
+```bash
+# Release a build to a distribution repository and tag it
+wp-release deploy-git build --git-url git@github.com:me/my-plugin-dist.git --branch main --tag 1.2.0
+
+# Release a monorepo package with its own history
+wp-release deploy-git packages/my-plugin --split-prefix packages/my-plugin --git-url … --branch main
+```
+
+How a deploy works:
+
+1. The selected files are written to the object database of the source repository and become a tree, with a temporary index, so the working tree and the index of the repository are left alone. Executable files stay executable.
+2. The previous release is fetched: the tip of `--branch`, or for a tag-only deploy the tip of the repository's default branch (its `HEAD`), whatever that branch holds. Release a tag together with `--branch` to choose the branch it builds on.
+3. When the files are the same as in the previous release, that release is reused. Otherwise a release commit is created with the files, whose parents are the previous release and the source history: the source commit (`--source-ref`, default `HEAD`), or with `--split-prefix` the history of that directory from `git subtree split`. The repository keeps the source history, and `git log --first-parent` lists the releases.
+4. When the previous release on `--branch` already has newer source history, the branch isn't moved, so running an older build again, like a re-run of an earlier CI job, can't release older files. The source history is outdated when it's an older commit of the source history that the previous release was made from, its last parent. `git subtree split` makes this reliable for `--split-prefix` too, since it creates the same commits for the same history. A revert is a new commit, so it's released, and with `--tag` the tag of an older build is still released, without moving the branch.
+5. The tag is checked in the repository first. A tag that already has the same files is the release: it's reused and nothing is pushed, so running a tag release again is a no-op. A tag with other files fails with exit code `2` before anything is pushed.
+6. The release is pushed to the branch, unless it didn't change or is outdated, and to the tag, in one atomic push. Pushes are never forced, so the branch only moves forward and a tag is never replaced, also when it was created in the meantime.
+
+To release a tag again, for example after a release with the wrong files, delete the tag in the repository (`git push <url> :refs/tags/<tag>`) and run the deploy again. There's no flag for replacing a tag, since installs, Composer and GitHub Actions pins trust that a published tag doesn't change.
+
+`--dry-run` runs everything except the push. `--message` sets the commit message, which defaults to `Release <tag or branch> from <source commit>`. Credentials come from git, like a token in the URL or an SSH key, and credentials in URLs are never printed. The commit needs a git identity (`user.name` and `user.email`).
+
 ### Exit codes
 
 | Code | Meaning |
 |---|---|
 | `0` | Success, dry run, no changes, or help |
-| `1` | Unexpected failure, such as a failed svn command |
-| `2` | Invalid options, failed release checks, an existing SVN tag, or files that don't match the checksums |
+| `1` | Unexpected failure, such as a failed svn or git command |
+| `2` | Invalid options, failed release checks, an existing SVN tag, a Git tag that exists with another release, or files that don't match the checksums |
 | `3` | Missing SVN credentials, or credentials that SVN rejected |
 
 ## Library
@@ -377,6 +423,24 @@ const { committed, revision, version, changes } = await new SvnDeploy(
 
 `resolveDeployOptions()` applies the defaults and throws a `ValidationError` (with `exitCode` `2`) for invalid combinations. `SvnDeploy` exposes each step (`prepare()`, `checkVersions()`, `checkout()`, `sync()`, `commit()` and `cleanup()`) separately so CI wrappers can run and report them one by one; `run()` runs all of them, or nothing when there's nothing to write. `getPlan()` lists the planned SVN changes. The `Svn` class wraps the svn command line, and takes the command runner as a dependency so that tests can replace it.
 
+Git deploys:
+
+```js
+import { GitDeploy, resolveGitDeployOptions } from '@wpelevator/wp-release';
+
+const { revision, created, pushed } = await new GitDeploy(
+	resolveGitDeployOptions( {
+		sourceDir: 'packages/my-plugin',
+		gitUrl: 'git@github.com:me/my-plugin.git',
+		branch: 'main',
+		tag: '1.2.0',
+		splitPrefix: 'packages/my-plugin',
+	} )
+).run();
+```
+
+`resolveGitDeployOptions()` throws a `ValidationError` without a repository URL or with an invalid branch or tag. `GitDeploy` exposes `createTree()`, `fetchPrevious()`, `createRelease()`, `isOutdated()`, `checkTag()`, `getRefsToPush()` and `push()` separately, like `SvnDeploy`, and takes a git command runner from `createGitRunner()` as a dependency. The result has `outdated` when the branch wasn't moved for older source history, the refs to write in `planned` and the refs that were pushed in `pushed`, which is empty in a dry run. `redactUrls()` hides the credentials in URLs.
+
 ### Logging
 
 `Logger` filters messages by level and passes them to a writer, like the transports of other Node.js loggers. The writer decides how messages look:

package/dist/changeset-config.d.ts

@@ -87,6 +87,8 @@ export interface ChangesetConfig {
     changelogInsertAfter?: string;
     /** Calculate a package's next version instead of using stable SemVer bumps. */
     nextVersion?: (input: NextVersionInput) => string;
+    /** Format the release notes of a tag, for example to add links. */
+    releaseNotes?: (input: ReleaseNotesInput) => string | Promise<string>;
 }
 /** Inputs supplied to a custom next-version strategy. */
 export interface NextVersionInput {
@@ -95,6 +97,26 @@ export interface NextVersionInput {
     currentVersion: string;
     changesets: Changeset[];
 }
+/** A commit of a package release. */
+export interface ReleaseCommit {
+    hash: string;
+    shortHash: string;
+    subject: string;
+}
+/** Inputs supplied to a custom release notes formatter. */
+export interface ReleaseNotesInput {
+    package: ChangesetPackage;
+    version: string;
+    tag: string;
+    /** Tag of the previous release of the package, without one for the first release. */
+    previousTag?: string;
+    /** The version's CHANGELOG.md section, or an empty string without one. */
+    changelog: string;
+    /** Commits that changed the package since the previous release, newest first. */
+    commits: ReleaseCommit[];
+    /** The default release notes: the changelog section, or the commit list without one. */
+    notes: string;
+}
 export type WpReleaseConfig = ChangesetConfig;
 export interface PackageJsonVersionOptions {
     file?: string;

package/dist/changeset-config.js

@@ -194,6 +194,10 @@ function validateChangesetConfig(config, configFile) {
         'function' !== typeof candidate.nextVersion) {
         throw new ValidationError(`wp-release config ${configFile}.nextVersion must be a function.`);
     }
+    if (undefined !== candidate.releaseNotes &&
+        'function' !== typeof candidate.releaseNotes) {
+        throw new ValidationError(`wp-release config ${configFile}.releaseNotes must be a function.`);
+    }
     candidate.packages.forEach((group, index) => {
         if ('object' !== typeof group ||
             null === group ||

package/dist/changeset-release.d.ts

@@ -1,4 +1,4 @@
-import type { Changeset, ChangesetReleasePlan, PackageRelease } from './changesets.ts';
+import type { Changeset, ChangesetPackage, ChangesetReleasePlan, PackageRelease } from './changesets.ts';
 export interface ChangesetRepository {
     cwd: string;
     configFile?: string;
@@ -6,6 +6,8 @@ export interface ChangesetRepository {
 export interface ChangesetVersionInput extends ChangesetRepository {
     dryRun?: boolean;
     date?: string;
+    /** Version only these packages, leaving the other changesets pending. */
+    packages?: string[];
 }
 export interface ChangesetTagInput extends ChangesetRepository {
     dryRun?: boolean;
@@ -13,12 +15,18 @@ export interface ChangesetTagInput extends ChangesetRepository {
     push?: boolean;
     githubRelease?: boolean;
     since?: string;
+    /** Tag only these packages. */
+    packages?: string[];
+    /** Expected version of the single package in `packages`. */
+    version?: string;
 }
 export interface ChangesetTagResult {
     tags: Array<{
         package: string;
         version: string;
         tag: string;
+        previousTag?: string;
+        prerelease: boolean;
         exists: boolean;
         created: boolean;
         notes: string;
@@ -31,6 +39,14 @@ export interface ChangesetTagResult {
  * @return A release plan; `undefined` when no config is present.
  */
 export declare function getChangesetReleasePlan(input: ChangesetRepository): Promise<ChangesetReleasePlan | undefined>;
+/**
+ * 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 declare function getChangesetPackages(input: ChangesetRepository): Promise<ChangesetPackage[]>;
 /**
  * Create a Changesets-compatible Markdown file.
  *

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 { formatChangelogEntries, 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,7 +122,10 @@ 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);
     if (!input.dryRun) {
         const journal = new Map();
@@ -128,9 +143,7 @@ export async function versionChangesets(input) {
             }
             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) {
@@ -147,6 +160,48 @@ export async function versionChangesets(input) {
         changed: !input.dryRun && releasePlan.changesets.length > 0,
     };
 }
+/**
+ * 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 +219,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 +246,8 @@ export async function tagChangesets(input) {
             package: pkg.name,
             version,
             tag,
+            ...(previousTag ? { previousTag } : {}),
+            prerelease: isPrerelease(version),
             exists,
             created: !exists && !dryRun,
             notes,
@@ -223,6 +287,7 @@ async function createGitHubRelease(cwd, release) {
                 `${release.package}@${release.version}`,
                 '--notes',
                 release.notes,
+                ...(release.prerelease ? ['--prerelease'] : []),
             ], { cwd });
         }
         catch (error) {
@@ -231,6 +296,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 +749,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${formatChangelogEntries(release.changesets)}\n\n`;
     const changelog = path.join(directory, 'CHANGELOG.md');
     let previous = '';
     try {
@@ -826,10 +1024,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

@@ -53,6 +53,13 @@ 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;
 /**
  * Return the strongest bump requested for a package across changesets.
  *

package/dist/changesets.js

@@ -64,6 +64,19 @@ 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 changesets
+        .map((item) => item.summary.trim())
+        .filter(Boolean)
+        .map((item) => `- ${item.replaceAll(/\r?\n/g, '\n  ')}`)
+        .join('\n');
+}
 /**
  * Return the strongest bump requested for a package across changesets.
  *