@wpelevator/wp-release 0.6.1 → 0.8.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,27 @@ 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.
 
+Configure `changelogEntry( { package, changeset, commit } )` to format the changelog entry of each changeset, where `commit` is the `{ hash, shortHash, subject }` of the commit that added the changeset file, if it's committed. The formatted entries go into `CHANGELOG.md`, the `changelog` of each release in the `changeset-version` result, and so the release notes; plugin readmes keep the plain summaries. `getGitHubPullRequest( { cwd, commit } )` finds the `{ number, url, author }` of the pull request that merged a commit with the authenticated `gh` CLI, for example to credit it:
+
+```js
+changelogEntry: async ( { changeset, commit } ) => {
+	const pullRequest = commit && ( await getGitHubPullRequest( { cwd: import.meta.dirname, commit: commit.hash } ) );
+
+	return pullRequest ? `${ changeset.summary } (#${ pullRequest.number } by @${ pullRequest.author })` : changeset.summary;
+},
+```
+
+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 +165,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 +177,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 +373,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 +433,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,10 @@ 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>;
+    /** Format the CHANGELOG.md entry of a changeset, for example to credit its pull request. */
+    changelogEntry?: (input: ChangelogEntryInput) => string | Promise<string>;
 }
 /** Inputs supplied to a custom next-version strategy. */
 export interface NextVersionInput {
@@ -95,6 +99,33 @@ 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;
+}
+/** Inputs supplied to a custom changelog entry formatter. */
+export interface ChangelogEntryInput {
+    package: ChangesetPackage;
+    changeset: Changeset;
+    /** Commit that added the changeset file, unless it isn't committed yet. */
+    commit?: ReleaseCommit;
+}
 export type WpReleaseConfig = ChangesetConfig;
 export interface PackageJsonVersionOptions {
     file?: string;

package/dist/changeset-config.js

@@ -194,6 +194,14 @@ function validateChangesetConfig(config, configFile) {
         'function' !== typeof candidate.nextVersion) {
         throw new ValidationError(`wp-release config ${configFile}.nextVersion must be a function.`);
     }
+    if (undefined !== candidate.changelogEntry &&
+        'function' !== typeof candidate.changelogEntry) {
+        throw new ValidationError(`wp-release config ${configFile}.changelogEntry 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, VersionedRelease } from './changesets.ts';
 export interface ChangesetRepository {
     cwd: string;
     configFile?: string;
@@ -6,6 +6,15 @@ export interface ChangesetRepository {
 export interface ChangesetVersionInput extends ChangesetRepository {
     dryRun?: boolean;
     date?: string;
+    /** Version only these packages, leaving the other changesets pending. */
+    packages?: string[];
+}
+/** Versioned releases, the applied changesets and whether files were changed. */
+export interface VersionChangesetsResult {
+    changesets: Changeset[];
+    releases: VersionedRelease[];
+    date: string;
+    changed: boolean;
 }
 export interface ChangesetTagInput extends ChangesetRepository {
     dryRun?: boolean;
@@ -13,12 +22,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 +46,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.
  *
@@ -48,10 +71,7 @@ export declare function addChangeset(input: ChangesetRepository & {
  * @param input Repository and versioning options.
  * @return Planned releases and whether files were changed.
  */
-export declare function versionChangesets(input: ChangesetVersionInput): Promise<ChangesetReleasePlan & {
-    date: string;
-    changed: boolean;
-}>;
+export declare function versionChangesets(input: ChangesetVersionInput): Promise<VersionChangesetsResult>;
 /**
  * Create missing release tags, optionally pushing them to the configured remote.
  *