# 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:

   ```bash
   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](https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/),
[Planning, submitting and maintaining](https://developer.wordpress.org/plugins/wordpress-org/planning-submitting-and-maintaining-plugins/),
[Plugin readmes](https://developer.wordpress.org/plugins/wordpress-org/how-your-readme-txt-works/),
[Plugin assets](https://developer.wordpress.org/plugins/wordpress-org/plugin-assets/),
[Using Subversion](https://developer.wordpress.org/plugins/wordpress-org/how-to-use-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](https://wordpress.org/plugins/developers/add/), 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.