@wpelevator/wp-release 0.2.0 → 0.3.0

package/README.md

@@ -153,6 +153,7 @@ wp-release version-check --constant MY_PLUGIN_VERSION --git-tag v1.2.0
 | Flag | Default | Writes |
 |---|---|---|
 | `--trunk` | off | Sync the full source directory to `trunk/` |
+| `--readme-only` | off | Sync only the readme to `trunk/`, for updates between releases such as bumping `Tested up to`. Can't be combined with `--svn-tag`. |
 | `--svn-tag <version>` | off | Copy `trunk/` to `tags/<version>`. Without `--trunk`, the tag is copied from the repository's current `trunk/`. A leading `v` is stripped, so `v1.2.0` creates `tags/1.2.0`. |
 | `--assets-dir <dir>` | not set | Sync this directory with banners, icons and screenshots to the SVN `assets/` directory. There's no default directory, so assets are only deployed when this is set, and it must exist. |
 | `--no-assets` | | Skip the `--assets-dir` sync for one run, for example when a config always passes `--assets-dir`. |
@@ -163,6 +164,9 @@ Typical runs:
 # Deploy 1.2.0 to trunk and the tag, and update the assets
 wp-release deploy-svn dist --trunk --svn-tag 1.2.0 --assets-dir .wordpress-org
 
+# Update only the readme between releases
+wp-release deploy-svn dist --readme-only
+
 # Update only the assets
 wp-release deploy-svn --assets-dir .wordpress-org
 
@@ -173,7 +177,7 @@ wp-release deploy-svn --from-zip my-plugin.1.2.0.zip --trunk --svn-tag 1.2.0
 How a deploy works:
 
 1. The options are validated, including the slug, version and readme name, before they're used in URLs or paths.
-2. With `--trunk`, the files must be a plugin whose `Version` header matches the version, and with `--svn-tag` the readme `Stable tag` must match too. A tag-only run doesn't check the files, since it tags whatever is in `trunk/`. Nothing is checked out when a check fails.
+2. With `--trunk`, the files must be a plugin whose `Version` header matches the version, and with `--svn-tag` the readme `Stable tag` must match too. A tag-only run doesn't check the files, since it tags whatever is in `trunk/`. `--readme-only` needs the readme. Nothing is checked out when a check fails.
 3. The repository is checked out sparsely into a new temporary directory, with only the directories that the flags write to. A missing `assets/` (or `trunk/`, `tags/`) directory is created. The deploy stops when `tags/<version>` exists, unless `--force` replaces it.
 4. The files are synced in Node.js, without `rsync`: new and changed files are copied, files that are no longer selected are deleted, and `svn add` and `svn delete` stage them, including files that svn ignores by default. `trunk/` is then copied to the tag with `svn copy`, from the working copy when trunk was written and from the repository otherwise.
 5. Asset images get `svn:mime-type` set for PNG, JPEG, GIF and SVG, the formats that WordPress.org documents for plugin assets. Other formats keep the type that svn assigns.
@@ -185,8 +189,9 @@ Credentials are only needed for the commit, not for dry runs, no-op runs or `fil
 
 Validation:
 
-- Pre-release versions like `1.0.0-rc.1` are never tagged.
+- `--readme-only` can't be combined with `--svn-tag`, since a tag is a release snapshot that a readme update never changes.
 - `--version` defaults to `--svn-tag`, then the `Version` header of the deployed files; when `--version` and `--svn-tag` are both set they must match.
+- Pre-release versions like `1.0.0-rc.1` can be tagged, but syncing one to `trunk/` warns, since trunk is for the development version.
 - `--trunk` without `--svn-tag` works but warns, because trunk then differs from the stable tag that WordPress.org serves downloads from.
 
 ### Exit codes
@@ -304,8 +309,8 @@ The `wpelevator-source` export condition points at `src/index.ts`. The tests and
 
 | Tool | What it does | How `wp-release` differs |
 |---|---|---|
-| [10up WordPress.org plugin deploy](https://github.com/10up/action-wordpress-plugin-deploy) and [readme/asset update](https://github.com/10up/action-wordpress-plugin-asset-update) actions | Two separate GitHub Actions configured through env vars. A deploy always syncs the build to `trunk/` and copies it to the tag; readme and asset updates need the second action. Assets come from `.wordpress-org` by default, and files are selected with `.distignore` or `.gitattributes`. Files are synced with `rsync`. | One `deploy-svn` command with independent write flags, so a release, a tag-only run and an assets-only update are the same command with different flags. Runs locally and in any CI, not only GitHub Actions, and syncs in Node.js without `rsync`. Checks that the `Version` header, readme `Stable tag` and SVN tag agree before writing, which the 10up actions don't. Assets are deployed only when `--assets-dir` is passed, instead of always syncing `.wordpress-org` when it exists, so a plugin's own `assets/` folder is never uploaded by accident. Adds `--exclude` for patterns without an ignore file and `--from-zip` to deploy the exact files of a ZIP. |
-| [`grunt-wp-deploy`](https://github.com/stephenharris/grunt-wp-deploy) | Grunt task with `deploy_trunk` and `deploy_tag` booleans, interactive password prompts and a `Stable tag` check. | No Grunt dependency and never interactive. Tagging is independent of syncing trunk, and assets are independent of both. |
+| [10up WordPress.org plugin deploy](https://github.com/10up/action-wordpress-plugin-deploy) and [readme/asset update](https://github.com/10up/action-wordpress-plugin-asset-update) actions | Two separate GitHub Actions configured through env vars. A deploy always syncs the build to `trunk/` and copies it to the tag; readme and asset updates need the second action. Assets come from `.wordpress-org` by default, and files are selected with `.distignore` or `.gitattributes`. Files are synced with `rsync`. | One `deploy-svn` command with independent write flags, so a release, a readme-only update and an assets-only update are the same command with different flags. Runs locally and in any CI, not only GitHub Actions, and syncs in Node.js without `rsync`. Checks that the `Version` header, readme `Stable tag` and SVN tag agree before writing, which the 10up actions don't. Assets are deployed only when `--assets-dir` is passed, instead of always syncing `.wordpress-org` when it exists, so a plugin's own `assets/` folder is never uploaded by accident. Adds `--exclude` for patterns without an ignore file and `--from-zip` to deploy the exact files of a ZIP. |
+| [`grunt-wp-deploy`](https://github.com/stephenharris/grunt-wp-deploy) | Grunt task with `deploy_trunk` and `deploy_tag` booleans, interactive password prompts and a `Stable tag` check. | No Grunt dependency and never interactive. `--readme-only` is a separate flag, where `grunt-wp-deploy` can only update trunk with the full build. Assets are independent of trunk writes. |
 | [codeinwp theme deploy](https://github.com/codeinwp/action-wordpress-theme-deploy) | Fork of the 10up plugin action that commits themes to the themes SVN repository. | Doesn't deploy themes. Theme releases are ZIP uploads on WordPress.org; `zip` builds the upload with the theme folder as the root. |
 | [`wp dist-archive`](https://github.com/wp-cli/dist-archive-command) | WP-CLI command that zips a project using `.distignore`, with `--plugin-dirname` and `--filename-format`. | Same `.distignore` file and `{name}.{version}` style filename format, but needs only Node.js instead of PHP and WP-CLI. `.distignore` is matched with full gitignore syntax, including `!` negation, and `--distignore` / `--exclude` let you point at another ignore file or add patterns on the command line. Builds are reproducible, and `--checksums` writes a manifest next to the ZIP. |
 | [`wp plugin verify-checksums`](https://developer.wordpress.org/cli/commands/plugin/verify-checksums/) | WP-CLI command that checks installed plugins against the WordPress.org checksums API. | Reads the same manifest format, but from a file, so it also works for plugins and themes that aren't hosted on WordPress.org and for build directories in CI. `checksums` writes the manifest that WordPress.org generates for its own plugins. |

package/dist/commands/deploy-svn.d.ts

@@ -41,6 +41,9 @@ declare const _default: {
         trunk: {
             type: "boolean";
         };
+        'readme-only': {
+            type: "boolean";
+        };
         'svn-tag': {
             type: "string";
         };

package/dist/commands/deploy-svn.js

@@ -19,6 +19,7 @@ export function getDeployInputFromArgs(input) {
         slug: getString(values, 'slug'),
         version: getString(values, 'version'),
         trunk: flag('trunk'),
+        readmeOnly: flag('readme-only'),
         svnTag: getString(values, 'svn-tag'),
         assets: getBoolean(values, 'no-assets') ? false : undefined,
         assetsDir: getString(values, 'assets-dir'),
@@ -42,6 +43,7 @@ export default {
 
 Writes (none by default, assets only with --assets-dir):
   --trunk                 Sync the full source directory to trunk/
+  --readme-only           Sync only the readme to trunk/ (not with --svn-tag)
   --svn-tag <version>     Copy trunk/ to tags/<version>, with or without
                           --trunk. A leading "v" is stripped.
   --assets-dir <dir>      Sync this directory with banners, icons and
@@ -70,11 +72,14 @@ or rejected.
 Examples:
   wp-release deploy-svn dist --trunk --svn-tag 1.2.0 --assets-dir .wordpress-org
       Deploy 1.2.0 to trunk and the tag, and update the assets
+  wp-release deploy-svn dist --readme-only
+      Update only the readme
   wp-release deploy-svn --assets-dir .wordpress-org
       Update only the assets`,
     options: {
         ...sourceDirArgs,
         trunk: { type: 'boolean' },
+        'readme-only': { type: 'boolean' },
         'svn-tag': { type: 'string' },
         'assets-dir': { type: 'string' },
         'no-assets': { type: 'boolean' },

package/dist/deploy-options.d.ts

@@ -13,6 +13,8 @@ export interface DeployInput {
     version?: string;
     /** Sync the full source directory to trunk/. */
     trunk?: boolean;
+    /** Sync only the readme to trunk/. */
+    readmeOnly?: boolean;
     /** Copy trunk/ to tags/<svnTag>. */
     svnTag?: string;
     /** Sync the assets directory, defaults to on when assetsDir is set. */
@@ -50,6 +52,7 @@ export interface DeployOptions extends FileSelection {
     slug: string;
     version: string | null;
     trunk: boolean;
+    readmeOnly: boolean;
     svnTag: string | null;
     assets: boolean;
     assetsDir: string | null;
@@ -117,7 +120,7 @@ export declare function getDeployOptionErrors(options: DeployOptions): string[];
  */
 export declare function getDeployOptionWarnings(options: DeployOptions): string[];
 /**
- * Apply defaults to deploy options and validate them. Trunk and tag
+ * Apply defaults to deploy options and validate them. Trunk, readme and tag
  * writes happen only when requested, and assets are synced whenever an
  * assets directory is set, unless turned off. The version defaults to the
  * SVN tag; without either, SvnDeploy reads the Version header of the

package/dist/deploy-options.js

@@ -62,9 +62,9 @@ function isValidFilename(name) {
  */
 export function getDeployOptionErrors(options) {
     const errors = [];
-    const { svnTag, version, assets, assetsDir, slug } = options;
-    if (svnTag && isPrerelease(svnTag)) {
-        errors.push(`Pre-release version ${svnTag} can't be tagged on WordPress.org.`);
+    const { readmeOnly, svnTag, version, assets, assetsDir, slug } = options;
+    if (readmeOnly && svnTag) {
+        errors.push("--readme-only can't be combined with --svn-tag, since a tag is a release snapshot that a readme update never changes.");
     }
     if (svnTag && !isValidVersion(svnTag)) {
         errors.push(`SVN tag "${svnTag}" isn't a valid version, use only letters, digits, dots, dashes, plus signs and underscores.`);
@@ -109,7 +109,7 @@ export function getDeployOptionWarnings(options) {
     return warnings;
 }
 /**
- * Apply defaults to deploy options and validate them. Trunk and tag
+ * Apply defaults to deploy options and validate them. Trunk, readme and tag
  * writes happen only when requested, and assets are synced whenever an
  * assets directory is set, unless turned off. The version defaults to the
  * SVN tag; without either, SvnDeploy reads the Version header of the
@@ -130,6 +130,7 @@ export function resolveDeployOptions(input = {}) {
         slug,
         version: input.version ? normalizeTag(input.version) : svnTag,
         trunk: Boolean(input.trunk),
+        readmeOnly: Boolean(input.readmeOnly),
         assets: input.assets ?? Boolean(assetsDir),
         svnTag,
         sourceDir,

package/dist/svn-deploy.d.ts

@@ -73,7 +73,8 @@ export declare class SvnDeploy {
     /**
      * Check the plugin files before anything is written. A trunk sync needs
      * a plugin with a Version header that matches the version, and with an
-     * SVN tag also a readme Stable tag that matches.
+     * SVN tag also a readme Stable tag that matches. Readme-only updates need
+     * the readme.
      *
      * @throws {ValidationError} When the files or versions don't match.
      */
@@ -184,7 +185,7 @@ export declare class SvnDeploy {
     /**
      * Check if the deploy reads plugin files, which assets-only runs don't.
      *
-     * @return Whether trunk is written.
+     * @return Whether trunk or the readme is written.
      */
     needsFiles(): boolean;
     /**

package/dist/svn-deploy.js

@@ -9,7 +9,7 @@ import { CredentialsError, ValidationError } from "./errors.js";
 import { loadFileRules, selectFiles } from "./file-selection.js";
 import { readPackageMeta } from "./package-meta.js";
 import { Svn } from "./svn.js";
-import { syncDirectory } from "./sync.js";
+import { copyFileIfChanged, syncDirectory } from "./sync.js";
 import { extractZip } from "./unzip.js";
 import { findVersionMismatches } from "./version-check.js";
 /**
@@ -97,27 +97,35 @@ export class SvnDeploy {
     /**
      * Check the plugin files before anything is written. A trunk sync needs
      * a plugin with a Version header that matches the version, and with an
-     * SVN tag also a readme Stable tag that matches.
+     * SVN tag also a readme Stable tag that matches. Readme-only updates need
+     * the readme.
      *
      * @throws {ValidationError} When the files or versions don't match.
      */
     async checkVersions() {
-        const { trunk, svnTag, slug } = this.options;
+        const { trunk, readmeOnly, svnTag, slug, readme } = this.options;
         const sourceDir = this.filesDir ?? this.options.sourceDir;
-        if (trunk) {
+        if (trunk || readmeOnly) {
             const meta = await this.readPluginMeta(sourceDir);
-            const { version, mismatches } = await findVersionMismatches({
-                sourceDir,
-                meta,
-                slug,
-                version: this.options.version,
-                stableTag: Boolean(svnTag),
-            });
-            this.version = version;
-            if (mismatches.length) {
-                throw new ValidationError(mismatches.map(({ message }) => message).join('\n'));
+            if (readmeOnly && !meta.readme) {
+                throw new ValidationError(`${readme} doesn't exist in ${sourceDir}.`);
+            }
+            if (trunk) {
+                const { version, mismatches } = await findVersionMismatches({
+                    sourceDir,
+                    meta,
+                    slug,
+                    version: this.options.version,
+                    stableTag: Boolean(svnTag),
+                });
+                this.version = version;
+                if (mismatches.length) {
+                    throw new ValidationError(mismatches
+                        .map(({ message }) => message)
+                        .join('\n'));
+                }
+                this.logger.info(`Deploying version ${version}.`);
             }
-            this.logger.info(`Deploying version ${version}.`);
         }
     }
     /**
@@ -187,7 +195,7 @@ export class SvnDeploy {
      * additions, deletions and asset MIME types, then copy trunk to the tag.
      */
     async sync() {
-        const { trunk, assets } = this.options;
+        const { trunk, readmeOnly, assets, readme } = this.options;
         const workingCopy = this.getWorkingCopy();
         const sourceDir = this.filesDir ?? this.options.sourceDir;
         if (trunk) {
@@ -197,6 +205,9 @@ export class SvnDeploy {
                 targetDir: join(workingCopy, 'trunk'),
             });
         }
+        if (readmeOnly) {
+            await copyFileIfChanged(join(sourceDir, readme), join(workingCopy, 'trunk', readme));
+        }
         if (assets) {
             await this.syncAssets();
         }
@@ -367,7 +378,7 @@ export class SvnDeploy {
      * @return Planned changes, in order.
      */
     getPlan() {
-        const { svnUrl, trunk, assets, assetsDir, force } = this.options;
+        const { svnUrl, trunk, readmeOnly, assets, assetsDir, readme, force } = this.options;
         const tagPath = this.getTagPath();
         const message = this.options.message ?? this.getDefaultMessage();
         const plan = [
@@ -377,6 +388,7 @@ export class SvnDeploy {
             tagPath && !force && `Stop if ${tagPath} already exists`,
             tagPath && force && `Replace ${tagPath} if it exists`,
             trunk && `Sync ${this.describeSource()} to trunk/`,
+            readmeOnly && `Copy ${readme} to trunk/`,
             tagPath && `Copy trunk/ to ${tagPath}`,
             assets && `Sync ${assetsDir} to assets/`,
             this.options.dryRun
@@ -392,9 +404,9 @@ export class SvnDeploy {
      * @return Relative paths with their SVN checkout depth.
      */
     getCheckoutPaths() {
-        const { trunk, svnTag, assets } = this.options;
+        const { trunk, readmeOnly, svnTag, assets } = this.options;
         const paths = [];
-        if (trunk) {
+        if (trunk || readmeOnly) {
             paths.push({ path: 'trunk', depth: 'infinity' });
         }
         if (svnTag) {
@@ -411,16 +423,16 @@ export class SvnDeploy {
      * @return Whether to check out and commit.
      */
     hasWrites() {
-        const { trunk, svnTag, assets } = this.options;
-        return Boolean(trunk || svnTag || assets);
+        const { trunk, readmeOnly, svnTag, assets } = this.options;
+        return Boolean(trunk || readmeOnly || svnTag || assets);
     }
     /**
      * Check if the deploy reads plugin files, which assets-only runs don't.
      *
-     * @return Whether trunk is written.
+     * @return Whether trunk or the readme is written.
      */
     needsFiles() {
-        return this.options.trunk;
+        return this.options.trunk || this.options.readmeOnly;
     }
     /**
      * Describe the files that are synced, including the ignore rules.
@@ -469,11 +481,15 @@ export class SvnDeploy {
         return null;
     }
     getDefaultMessage() {
-        const { trunk, svnTag, assets } = this.options;
+        const { trunk, readmeOnly, svnTag, assets } = this.options;
         if (svnTag) {
             return `Release version ${svnTag}`;
         }
-        const parts = [trunk && 'trunk', assets && 'assets'];
+        const parts = [
+            trunk && 'trunk',
+            readmeOnly && 'readme',
+            assets && 'assets',
+        ];
         return `Update ${parts.filter(Boolean).join(' and ')}`;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wpelevator/wp-release",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "Package, checksum, verify and version-check WordPress plugins and themes, and deploy plugins to WordPress.org SVN",
 	"license": "MIT",
 	"repository": {