wp-plugin-starter-template-for-ai-coding/RELEASING.md

Releasing

How every plugin made from the wpallstars starter plugin is released. This file is the same in each of them (names as placeholders: STANDARDS.md lists them, and the plugin's AGENTS.md gives its values). The plugin's own submission state and guideline review: LAUNCH.md.

Releases on GitHub and the WordPress.org submission need the owner's say. None of the scripts below tags, publishes, uploads or commits anything.

Scripts

Script	What it does
scripts/build-release.sh [--ref REF] [--out DIR]	Builds both zips from a Git ref (default HEAD) into dist/ (gitignored), with SHA256SUMS. Files come from Git, never the working tree.
scripts/preflight-release.sh [--ref REF] [--strict] [--offline]	Checks versions, headers, readme, both zips (layout, development files, PHP 7.4 and JS syntax, updater code), remote assets, presets and starter data where the plugin has them, and the Git tag. Errors stop a release; --strict also fails on warnings, for a WordPress.org submission.
scripts/plugin-check.sh [--ref REF] [--zip FILE]	Runs Plugin Check on both zips in a disposable WordPress in Docker, then removes it.

The two builds of each version:

Zip	Contents	Goes to
{slug}-X.Y.Z.zip	Files in Git, less .distignore	GitHub release asset
wordpress-org-{slug}-X.Y.Z.zip	The same, less .distignore-wporg (the GitHub updater) and the GitHub Plugin URI, Primary Branch and Release Asset header lines	WordPress.org only

Sites install the release asset whose name starts with {slug} (the shared GitHub updater, and Git Updater where it is still active), so the WordPress.org zip is named differently and must never be attached to a GitHub release.

Plugin Check reports the GitHub updater as an updater (plugin_updater_detected, update_modification_detected, and OffloadedContent for its raw.githubusercontent.com address) and its shared wpallstars_ names as unprefixed, in the GitHub zip; scripts/plugin-check.sh lists those as expected there and fails on the updater findings in the WordPress.org zip.

GitHub release

1. In a pull request, set the version in {slug}.php (Version: and {PREFIX}_VERSION) and readme.txt (Stable tag:), rename the changelog's Unreleased section to the version in readme.txt, changelog.txt and README.md, and add an upgrade notice if people need to act. readme.txt keeps only the newest version, in short, and must stay under 10 KB; changelog.txt keeps every version in full. Numbers only (1.2.3): sites still on Git Updater offer a Version: on main to every site, and the shared updater skips tags with letters.

2. On the pull request's branch: scripts/preflight-release.sh (no errors) and scripts/plugin-check.sh (no errors).

3. Merge, then straight away:

   git fetch origin
   scripts/preflight-release.sh --ref origin/main   # no errors before tagging
   git tag -a vX.Y.Z origin/main -m "{Name} X.Y.Z"
   scripts/build-release.sh --ref vX.Y.Z
   git push origin vX.Y.Z
   gh release create vX.Y.Z dist/{slug}-X.Y.Z.zip --title "{Name} X.Y.Z" --notes-file <notes>
   

   Sites with the shared updater see the release when they next check. Sites still on Git Updater are offered the Version: on main before the release exists, so do this in the same sitting as the merge.

4. Check the release has exactly one asset, {slug}-X.Y.Z.zip, and on a site with the previous version that Check again on the Updates screen shows the update and that it installs.

Sites read the repository without signing in, so it must be public for sites to get updates. While it is private, a test site can use a read-only token in WPALLSTARS_GITHUB_TOKEN (wp-config.php; it serves every plugin with the shared updater). Making it public needs the owner's say; do the quality sweep in DEVELOPMENT.md → At public launch in the same step.

WordPress.org

Guidelines: Detailed Plugin Guidelines, Planning, submitting and maintaining, Plugin readmes, Plugin assets, Using Subversion.

Before submitting, work through the plugin's LAUNCH.md: what scripts/preflight-release.sh --strict still reports, and a review of the code against each guideline (no code from elsewhere, external services, scripts and styles shipped with the plugin, links, admin notices, defaults, files outside the plugin folder, uninstall, GPL, name and trademarks, a complete plugin).

Submitting

1. scripts/build-release.sh --ref vX.Y.Z (a version already released on GitHub), then scripts/preflight-release.sh --ref vX.Y.Z --strict passes, or every warning is accepted.
2. scripts/plugin-check.sh --ref vX.Y.Z reports no errors; read every warning.
3. Test the WordPress.org zip on a clean site (latest WordPress and 6.2 with PHP 7.4), with WP_DEBUG on: activate, turn each feature on and off, deactivate, delete. debug.log stays empty.
4. Signed in as the owner's WordPress.org account, upload dist/wordpress-org-{slug}-X.Y.Z.zip at Add your plugin, and ask for the {slug} slug in the notes.
5. Review takes about 1 to 10 business days. Reply to the reviewer's email from the same account; fix issues in the repository, not in a copy.

After approval (Subversion)

The SVN repository is https://plugins.svn.wordpress.org/{slug}/ (or the slug given). It is for releases only, not development. The SVN password is separate from the account password and is set on the WordPress.org profile (see Using Subversion). Install Subversion first (brew install subversion).

1. Check out the empty repository: svn co https://plugins.svn.wordpress.org/{slug}/ svn-{slug}.
2. Unzip the WordPress.org build's {slug}/ folder into trunk/ (no zip files in SVN), svn add new files, svn rm removed ones.
3. Copy trunk to the tag: svn cp trunk tags/X.Y.Z. Stable tag: in trunk/readme.txt and tags/X.Y.Z/readme.txt must be X.Y.Z; never trunk.
4. Put the banners, icons and screenshots in assets/.
5. svn ci -m "Release X.Y.Z", then check the plugin page and download.
6. Consider release confirmation emails (Plugin Handbook → Release Confirmation Emails), so a release goes out only after it is confirmed.

Each later WordPress.org release: build from the tag that is already on GitHub, --strict preflight, Plugin Check, then steps 2 to 5. Readme-only changes (such as raising Tested up to) go to trunk and the current tag.

Once listed, sites with the GitHub build update from WordPress.org, unless the plugin returns true from wpallstars_github_updater_early (a setting such as Early updates from GitHub), which keeps them on GitHub releases.