Files

T

kristianwindandClaude Opus 5 200f791f40 An icon, a Check again that checks, and the auto-update rule written down

Three gaps found by being asked plain questions about it.

**The auto-update toggle was a promise nobody had checked.** offer_update()
answers even when the installed version is current, on the reasoning that the
answer has to land in WordPress's no_update list for the "Enable auto-updates"
link to exist at all. That was a comment and an intention; it is now an
assertion against the real WP_Plugins_List_Table, which is where the flag is
actually read:

    $plugin_data = array_merge( (array) $plugin_info->no_update[ $plugin_file ],
                               array( 'update-supported' => true ), $plugin_data );

A plugin in neither response nor no_update gets "Auto-updates are not available
for this plugin" while looking entirely healthy.

**An icon.** Without one, Dashboard → Updates shows a generic grey plug.
assets/icon.svg, handed over in the offer's icons key, served from the shop's
own copy rather than the release host — one fewer thing that must be reachable
for wp-admin to render, and it cannot go mixed content on an HTTPS shop. Drawn
as paths rather than <text>: an SVG that leans on a font renders differently on
every machine, and this one is shown at about 40px, which is the size where
that is the difference between a mark and a smudge.

**"Check again" now checks again.** The six-hour cache is right for the check
WordPress runs twice a day and wrong for a link whose whole promise is that it
looks now. Publishing a release and then clicking it showed nothing for up to
six hours, which reads exactly like a broken updater.

And docs/REUSE.md was missing all of this: it covered Update URI, where to
instantiate the updater and making the repo public, but not the one rule that
is genuinely easy to get wrong.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-09-16 12:23:05 +02:00

6.6 KiB

Raw Permalink Blame History

Using this setup in another plugin

Everything here was built to be lifted into the next WordPress plugin. Nothing under ci/ knows this plugin's name except ci/plugin.conf.

There is no shared repository and no reusable workflow to uses:. That is deliberate: these repositories live on two forges, and a cross-forge workflow_call resolves on GitHub and fails on Gitea. Copying six files and editing one is a smaller cost than a dependency that works in half the places it runs.

The port

1. Copy these, unchanged:

ci/                        every script; plugin.conf is the only one you edit
.github/workflows/         ci.yml, compat.yml, release.yml, auto-merge.yml
.gitea/workflows/          ci.yml, compat.yml, release.yml, README.md
.distignore

2. Rewrite ci/plugin.conf — five values, all commented in the file:

PLUGIN_SLUG=your-plugin
PLUGIN_MAIN=your-plugin.php
TEXT_DOMAIN=your-plugin
NEEDS_WOOCOMMERCE=yes        # no, for a plugin that does not need it
SITE_TESTS="tests/fixtures.php tests/smoke.php"

3. Adjust .distignore for that plugin's internal documents. Everything left in wp-content/plugins/ can in principle be fetched over HTTP from a live shop, so notes and tooling stay out of the zip.

4. Write tests/fixtures.php and tests/smoke.php. These are the only genuinely new work. Use this plugin's as the shape: wc_edm_ok() / wc_edm_is() accumulate failures so one run reports all of them, and the file exits non-zero at the end. They run under wp eval-file, so WordPress and WooCommerce are fully loaded and every API is the real one.

5. Copy includes/class-updater.php and rename the class, the TRANSIENT constant, the plugin-file constant and the user-agent string. Then add to the plugin header:

Update URI:  https://gitea.nolimit.dk/kw/your-plugin

and instantiate the updater before any "is WooCommerce active" gate — a shop with WooCommerce switched off for an afternoon must not quietly stop receiving fixes.

Three things in that file are load-bearing and none of them look it:

🔴 offer_update() answers even when the installed version is already current. It is tempting to return false there — there is no update, after all — and that one line is what silently removes the Enable auto-updates link from the Plugins screen. WP_Plugins_List_Table sets update-supported only for plugins it finds in the update transient's response or no_update list; a plugin that stays silent is in neither, and wp-admin says "Auto-updates are not available for this plugin." The plugin looks perfectly configured and can never auto-update. tests/smoke.php asserts the rendered table, not the intention.
Set icons. Without it Dashboard → Updates shows a generic grey plug. Point it at the shop's own copy (PLUGIN_URL . 'assets/icon.svg'), not the release host: one fewer thing that must be reachable for wp-admin to render, and it cannot go mixed-content on an HTTPS shop.
Update URI also switches wordpress.org off for this plugin, from WordPress 5.8. Remove the header and a .org plugin that happens to share the slug could be pushed onto a shop running yours.

The answer is cached for six hours, which is right for the check WordPress runs twice a day and wrong for the Check again link — so forget_on_force_check() drops the cache on force-check. Without it, someone who has just published a release clicks that link, sees nothing, and concludes the whole mechanism is broken.

6. Make the Gitea repository public, or point Update URI at a separate public releases-only repository. Every shop reads that feed without credentials; ci/publish-release.sh fails the release with this instruction if it cannot.

What you get

ci/static.sh — syntax on the oldest and newest PHP, the direct-access guard on every shipped file, no debug leftovers, no short tags, text domain on every translation call, one version stated once across header, constant and readme, and a warning when the compatibility headers have gone stale.
ci/site-test.sh — a real WordPress + WooCommerce at any versions you name, including nightly and beta, failing on any deprecation from your own code.
ci/build-zip.sh — an installable zip, checked for the main file, for a single top-level directory named for the slug, and for leaked tooling.
compat.yml — the weekly run against the next WordPress and the next WooCommerce, and a pull request that bumps the compatibility headers once that run is green.
release.yml — tag, test, build, publish, then read the feed back with no credentials to prove a shop can download it.
ci/update-smoke.sh — install the previous version into a throwaway shop and let WordPress update it by itself. The only check that proves the whole chain.
Assertions that the Enable auto-updates link is actually offered, built from the real WP_Plugins_List_Table, and that the update offer carries an icon that exists in the release.
ci/workflows-in-sync.sh — fails when the two workflow roots drift, which is the only way to notice that a workflow stopped running on Gitea.

Two guards worth understanding before you move them

.gitea/workflows/ hides .github/workflows/ completely. Gitea uses the former if it exists and never merges the two. Adding one Gitea-only workflow switches off CI for the whole repository there, with no error and no run to click on — it looks exactly like a runner that has not picked the job up. Every workflow that must run on Gitea has to be in that directory.

The release reads its own feed anonymously afterwards. A private repository and a release with no zip attached both produce a page that looks perfect to anyone logged in, and an update that no shop is ever offered. A check that sends a token is the false positive that hides exactly that.

A forge's own download URL is not the address your users can reach. browser_download_url is built from the forge's configured root URL; gitea.nolimit.dk reports http://57.129.89.117:25001/... there. The updater rebuilds the address from the Update URI header and keeps only the path. This one hides particularly well: a CI job on the same network reaches that raw IP, so following the reported URL goes green and only a real client outside fails.

Candidates already in the fleet

spool and subscriptions are both WooCommerce plugins with some of this already: spool has an earlier version of the throwaway-site script, and subscriptions has the hygiene checks and a .distignore. Neither has the version matrix, the compatibility schedule or the updater. Porting them is steps 1–5 above.

6.6 KiB Raw Permalink Blame History Unescape Escape