kw/nolimit-discounts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Test against the newest WordPress and WooCommerce, and ship updates

Browse Source 
Three things this repository could not do: prove the plugin still works on a
WordPress or WooCommerce released after it, get a fix onto a shop without
someone uploading a zip, and do either of those for the next plugin without
starting over.

ci/ is the test harness. ci/site-test.sh builds a throwaway WordPress +
WooCommerce in containers at any versions you name — including `nightly` and
`beta` — installs exactly the files the release zip will contain, and runs
tests/smoke.php inside it with wp eval-file. Real cart, real coupons, real
WC_Shipping_Rate objects: a mocked cart keeps passing after WooCommerce has
changed underneath it, which is the one failure worth catching here. WP_DEBUG
is on and any notice logged from this plugin's directory fails the build,
because that is the shape an upgrade actually breaks in — nothing fails, a
notice appears, and two releases later it is a fatal.

compat.yml runs that weekly against today's releases, the next WordPress and
the next WooCommerce, the oldest PHP the header promises and the newest PHP.
When it is green it opens a PR bumping "Tested up to" and "WC tested up to" —
only when green, because WooCommerce shows that second value to the shop owner
as an untested-plugin banner, and that banner is what they read before deciding
whether to press update.

includes/class-updater.php is the distribution half. It hooks
update_plugins_{hostname} for the host in the new "Update URI" header and reads
the Gitea release API, so WordPress handles the notice, the download, the
"Enable auto-updates" link and wp plugin update with no further code. Update
URI earns its place twice: since 5.8 a plugin that declares one is never asked
about on wordpress.org, so a .org plugin sharing this slug cannot be pushed
onto a shop running this one. The check sends nothing about the site and
overrides WordPress's default user agent, which carries the site's own URL.

release.yml tags, tests, builds, publishes — then reads the feed back with no
credentials. A private repository and a release with no zip attached both leave
a page that looks perfect to anyone logged in and an update no shop is ever
offered.

Measured before committing, all green: WP 7.1 + WC 11.1 on PHP 8.3 and 7.4,
WP 7.2-alpha on 8.3, and the beta cell falling back to stable on 8.4. No
deprecations from this plugin on any of them.

Three guards are there because the bug they catch is invisible without them:
the annotated tag is re-fetched before its message is read (checkout turns it
into a lightweight tag pointing at the merge commit), the two workflow roots
are kept in sync (.gitea/workflows hides .github/workflows entirely), and every
file the code loads must be in the release zip — which caught class-updater.php
being referenced and uncommitted while every local test passed.

docs/REUSE.md is the port to the next plugin: copy ci/, rewrite five lines.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
kristianwind
2026-09-16 10:34:38 +02:00
co-authored by Claude Opus 5
parent e4a40e53a0
commit eca2851d35
29 changed files with 2550 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/REUSE.md
+97
View File
@@ -0,0 +1,97 @@
# 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:
```sh
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.
**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/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.
## 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.
docs/TESTING-AND-RELEASES.md
+158
View File
@@ -0,0 +1,158 @@
# Testing, releases and automatic updates
Three questions, answered by three things in this repository.
| Question | Answer |
| --- | --- |
| Does it still work on the newest WordPress and WooCommerce? | `ci/site-test.sh`, run weekly by `compat.yml` against `latest`, `nightly` and `beta` |
| Can updates be pushed out automatically? | Yes — `includes/class-updater.php` plus `release.yml` |
| What happens when *I* press update in wp-admin? | Nothing surprising, because the release was tested against those versions before it was published |
---
## Running the tests
```sh
ci/static.sh # syntax, hygiene, versions, headers — seconds
ci/site-test.sh # a real WordPress + WooCommerce — a few minutes
ci/build-zip.sh # what a shop actually installs
```
`ci/site-test.sh` takes three knobs:
```sh
WP_VERSION=latest # or nightly, or an exact version like 7.0
WC_VERSION=latest # or beta, or an exact version like 11.1.0
PHP_VERSION=8.3 # any tag of the wordpress:cli image
```
It builds a throwaway site in Docker containers, installs WordPress and
WooCommerce at those versions, copies in **exactly the files the release zip
will contain**, activates the plugin, and runs `tests/fixtures.php` and
`tests/smoke.php` inside it with `wp eval-file`.
The tests use a real cart, real coupons and real `WC_Shipping_Rate` objects.
That is the point. A mocked cart keeps passing after WooCommerce has changed
underneath it, which is the one failure this whole directory exists to catch.
Everything is torn down afterwards — containers, volumes and the network — so
running it twice leaves nothing behind.
### Deprecations count as failures
The site test switches on `WP_DEBUG` and fails the build on any notice logged
from this plugin's directory. That is how a WordPress or PHP upgrade actually
breaks a plugin: nothing fails, a notice appears, and two releases later it is
a fatal. Notices from WordPress core and WooCommerce are ignored — failing on
those would make the build red for something nobody here can fix, and a build
that is always red is a build that gets ignored.
---
## The weekly compatibility run
`compat.yml` runs the matrix every Monday at 06:00 and on demand:
| WordPress | WooCommerce | PHP | What it tells you |
| --- | --- | --- | --- |
| latest | latest | 8.3 | today's shop |
| **nightly** | latest | 8.3 | the next WordPress, weeks early |
| latest | **beta** | 8.3 | the next WooCommerce, weeks early |
| latest | latest | 7.4 | the floor the plugin header promises |
| latest | latest | 8.4 | where deprecations appear first |
The `beta` cell falls back to the stable release when there is no open beta, so
it is never silently skipped.
When the whole matrix passes, a second job compares `Tested up to:` and
`WC tested up to:` against the current releases and opens a pull request if
they are behind. It runs only after the matrix is green, because those headers
are a claim — WooCommerce shows `WC tested up to` to the shop owner as an
untested-plugin banner, and that banner is what they read before deciding
whether to press update.
The schedule fires on both forges; the matrix job skips the scheduled run on
Gitea so the single self-hosted runner is not asked to repeat GitHub's work.
`workflow_dispatch` still works there.
---
## Cutting a release
1. Bump `Version:` in the plugin header. `ci/static.sh` checks that
`WC_EDM_VERSION` and the readme's `Stable tag:` agree with it — WordPress
compares the update feed against the header and nothing else, so a
disagreement means the update is offered again immediately after it is
installed, forever.
2. Add a changelog section to `README.txt`.
3. Merge to `main`.
4. Tag it **annotated**, because the message is the release notes:
```sh
git tag -a v1.4.0 -m "..."
git push origin v1.4.0 # origin pushes to GitHub and Gitea both
```
`release.yml` then runs the static checks, installs the plugin into a real
WordPress + WooCommerce and runs the full test suite, builds the zip, publishes
the release, and finally **reads the feed back anonymously** to prove a shop
can actually download it.
Two things in there are guards against bugs that are invisible without them:
- **The tag message is re-fetched before it is read.** `actions/checkout`
fetches every tag correctly and then overwrites the triggering one with the
commit SHA, turning an annotated tag into a lightweight one. Reading it then
returns the *commit* message — on a merge commit, "Merge pull request #12
from …". Nothing fails; the release is just published with the wrong text.
- **The anonymous read-back sends no credentials.** The two ways the feed
breaks — a private repository and a release with no zip attached — both
leave a release page that looks perfectly fine to anyone logged in.
---
## How the automatic updates work
The plugin header carries:
```
Update URI: https://gitea.nolimit.dk/kw/woocommerce-email-discount-manager
```
`includes/class-updater.php` hooks `update_plugins_gitea.nolimit.dk`, the
filter WordPress fires for plugins whose `Update URI` points at that host. It
reads `/api/v1/repos/kw/<repo>/releases/latest`, takes the tag as the version
and the attached `.zip` as the package, and hands both to WordPress. WordPress
does the version comparison, the download, the unpacking and the rollback.
That means all of this works with no extra code:
- the update notice on **Plugins** and **Dashboard → Updates**
- the **update now** link
- the per-plugin **Enable auto-updates** link — WordPress builds that from the
plugins it has an answer for, which is why the updater answers even when the
installed version is already current
- `wp plugin update woocommerce-email-discount-manager` over WP-CLI
`Update URI` earns its place a second way: since WordPress 5.8, a plugin that
declares one is **never asked about on wordpress.org**. Without it, a .org
plugin that happened to share this slug could be pushed onto a shop running
this one.
### One-time setup
The repository on Gitea must be **public**, because every shop reads that feed
without credentials. Settings → make it public. Nothing in a GPL plugin zip is
secret, and the release workflow fails loudly with this exact instruction if it
is not done.
If you would rather keep the source private, create a separate public repo that
holds only releases and point `Update URI` at that instead — the updater
derives everything else from the header, so that is a one-line change.
### It reports nothing
The update check sends a plain unauthenticated GET for a file every visitor to
that repository can read. The user agent is overridden on purpose: WordPress's
default one is `WordPress/7.1; https://the-shop.example`, which would tell the
update host which shops are running this plugin. Nothing else about the site
leaves it, ever.