Repository navigation
Add update-wp-version: Tested up to, and optionally Requires at least, in the readme and the plugin file #24
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
Open
Changes from all commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
ddfe327
Add update-wp-version: Tested up to, and optionally Requires at least…
larodiel 94c054a
update-wp-version replaces the whole previous version, a pre-release …
larodiel 901d2fe
update-wp-version takes a plugin file .puprc lists with a leading ./
larodiel 49cd90a
update-wp-version sets the latest WordPress release when tested-up-to…
larodiel a206ad2
update-wp-version takes min-version: empty leaves it, auto counts two…
larodiel d9fafb2
update-wp-version never lowers Tested up to, reports each header per …
larodiel 3840598
update-wp-version's action.yml describes every case the changed outpu…
larodiel 5a142c3
update-wp-version never lowers Requires at least with min-version auto
larodiel 80a9209
update-wp-version refuses an automatic minimum below 1.0, and keeps a…
larodiel File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,118 @@ | ||
| # update-wp-version | ||
|
|
||
| Sets the WordPress version a plugin is tested up to and, when asked, the minimum it requires: a | ||
| version given, or two minor versions behind. | ||
|
|
||
| ```yaml | ||
| - uses: actions/checkout@v6 | ||
| with: | ||
| ref: ${{ inputs.branch }} | ||
| persist-credentials: false | ||
|
|
||
| - uses: stellarwp/plugin-toolbox/.github/actions/update-wp-version@v1 | ||
| id: wp | ||
| with: | ||
| # Empty sets the latest WordPress release. | ||
| tested-up-to: ${{ inputs.tested-up-to }} | ||
| # Empty leaves Requires at least; `auto` sets it two minors back; `6.9` sets exactly that. | ||
| min-version: ${{ inputs.min-version }} | ||
|
|
||
| # Commit here, when steps.wp.outputs.changed is 'true': this action only writes files. | ||
| ``` | ||
|
|
||
| It commits nothing: the step that commits the release preparation carries the change. | ||
|
|
||
| ## What it writes | ||
|
|
||
| | Header | `readme.txt` | Plugin file | | ||
| |---|---|---| | ||
| | `Tested up to:` | always | when the file carries the header | | ||
| | `Requires at least:` | when `min-version` is set | when `min-version` is set | | ||
|
|
||
| An empty `tested-up-to` is the latest WordPress release: the first offer | ||
| `https://api.wordpress.org/core/version-check/1.7/` returns. A version passed in is used as it is. | ||
|
|
||
| `min-version` takes a version, which is set as it is, or `auto`. `auto` is the tested version two | ||
| minors back, major and minor only: `6.8` and `6.8.1` both give `6.6`. WordPress runs each major from | ||
| x.0 to x.9 and then moves to the next (6.9 was followed by 7.0), so `auto` counts back across a | ||
| major the same way: `7.0` gives `6.8` and `7.1` gives `6.9`. `auto` never lowers a minimum: a file | ||
| at `6.9` stays at `6.9` when `auto` gives `6.8`, and the run reports it. A version given exactly is | ||
| set as it is, so passing `6.7` is how a plugin lowers its minimum on purpose. | ||
|
|
||
| The plugin file is the single root-level `.php` file `.puprc` lists under `paths.versions`. Some | ||
| plugins keep `Tested up to:` there as well as in `readme.txt`, as LearnDash does in `sfwd_lms.php`, | ||
| so the action sets it in both. | ||
|
|
||
| Only an existing header is rewritten. A file without the header is left as it is, and a missing | ||
| `readme.txt` is skipped. Only the first line carrying a header changes, so a version quoted further | ||
| down the file stays. `Tested up to` is never lowered: a file at `7.1.4` stays at `7.1.4` when | ||
| `tested-up-to` is `7.1`, and the run reports it. The whole value is | ||
| replaced, so `Tested up to: 6.8-RC1` becomes `Tested up to: 6.8`. When no file carries a header to set, the action writes a warning and passes. | ||
|
|
||
| The log and the job summary say, for each header each file carries, whether it changed from one | ||
| version to another, was already at the version, or was left above it. The `changed` output is | ||
| `true` when any file was written. | ||
|
|
||
| ## What the repository needs | ||
|
|
||
| Nothing to set `Tested up to:` in `readme.txt`. For the plugin file, a `.puprc` that lists it: | ||
|
|
||
| ```json | ||
| { | ||
| "paths": { | ||
| "versions": [ | ||
| { "file": "the-events-calendar.php", "regex": "(Version: )(.+)" }, | ||
| { "file": "readme.txt", "regex": "(Stable tag: )(.+)" } | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| The same file listed several times, once per regex, counts as one. A leading `./` is allowed: | ||
| `./the-events-calendar.php` is the same root file. | ||
|
|
||
| ## What it refuses | ||
|
|
||
| Every check runs before any file is written, so a refused run changes nothing. | ||
|
|
||
| - `tested-up-to` that is not two or three numeric parts: `banana`, `6`, `6.8.1.2`, `v6.8`. A | ||
| zero-padded part is refused too, such as `6.08` or `06.8`. | ||
| - An empty `tested-up-to` when the latest release cannot be looked up: the request fails, the | ||
| answer is not JSON, or its first offer holds no such version. | ||
| - `min-version` that is not empty, `auto`, or a version of the same shape as `tested-up-to`, or a | ||
| version above `tested-up-to`. | ||
| - `min-version: auto` with a tested version below `1.2`, which has no minimum two minors back. | ||
| - `working-directory` that is not a directory. | ||
| - With `min-version` set, a `.puprc` that is missing, is not JSON, has no `paths.versions`, or does | ||
| not list exactly one root-level PHP file that exists. | ||
|
|
||
| With `min-version` empty the `.puprc` is optional. Without one, or with one that does not name | ||
| a single plugin file, only `readme.txt` is updated. | ||
|
|
||
| ## Inputs | ||
|
|
||
| | Input | Required | Default | What it does | | ||
| |---|---|---|---| | ||
| | `tested-up-to` | no | the latest release | The WordPress version to set as `Tested up to`, e.g. `6.8` or `6.8.1`. Empty looks up the latest WordPress release | | ||
| | `min-version` | no | | The `Requires at least` version: empty leaves it, `auto` sets it two minor versions behind `tested-up-to` without lowering a higher one, a version such as `6.9` sets exactly that | | ||
| | `working-directory` | no | the workspace | Where the repository is checked out, relative to the workspace or absolute | | ||
|
|
||
| ## Outputs | ||
|
|
||
| | Output | Example | What it is | | ||
| |---|---|---| | ||
| | `min-version` | `6.6` | The minimum version set. Empty when the `min-version` input is empty | | ||
| | `changed` | `true` | `true` when a file was written, `false` when every header was already at its version, was left above it, or no file carries one | | ||
|
|
||
| ## How it runs | ||
|
|
||
| One [actions/github-script](https://github.com/actions/github-script) step runs | ||
| [`update-wp-version.js`](./update-wp-version.js). There is no dependency to install and nothing to | ||
| build. | ||
|
|
||
| Inputs reach the script through `process.env`, never by being interpolated into it, so a version is | ||
| data and cannot become part of the program. The script runs no command: it reads and writes files, | ||
| and with an empty `tested-up-to` it sends one request to `api.wordpress.org`. | ||
|
|
||
| `tests/actions/update-wp-version/update-wp-version.test.js` covers the rules above against real | ||
| temporary directories. Run `npm install` once, then `node --test`. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,64 @@ | ||
| # Sets the WordPress version a plugin is tested up to and, when asked, the minimum it requires: a | ||
| # version given, or two minor versions behind. It rewrites the headers in readme.txt and the plugin | ||
| # file only: it commits nothing, so the step that commits the release preparation carries the change. | ||
| # | ||
| # The logic lives in update-wp-version.js, run by actions/github-script, so there is no dependency | ||
| # to install and nothing to build. | ||
| name: Update the WordPress version | ||
| description: Sets the 'Tested up to' WordPress version and, optionally, the 'Requires at least' minimum | ||
|
|
||
| inputs: | ||
| tested-up-to: | ||
| description: >- | ||
| The WordPress version to set as `Tested up to`, e.g. `6.8` or `6.8.1`: two or three numeric | ||
| parts, none zero-padded. Empty is the latest WordPress release, read from | ||
| api.wordpress.org; a failed lookup fails the step. Anything else fails before any file is | ||
| written. | ||
| required: false | ||
| default: '' | ||
| min-version: | ||
| description: >- | ||
| The `Requires at least` version. Empty leaves it. `auto` sets it two minor versions behind | ||
| `tested-up-to`, e.g. `6.8.1` gives `6.6` and `7.0` gives `6.8`, and never lowers a higher | ||
| minimum a file already has. A version such as `6.9` sets exactly that, lower or not, and may | ||
| not be above `tested-up-to`. Anything else fails before any file is | ||
| written. | ||
| required: false | ||
| default: '' | ||
| working-directory: | ||
| description: >- | ||
| Where the repository is checked out, relative to the workspace or absolute. Empty is the | ||
| workspace. A directory that is not there fails before any file is written. | ||
| required: false | ||
| default: '' | ||
|
|
||
| outputs: | ||
| min-version: | ||
| description: 'The minimum version set, e.g. `6.6`. Empty when `min-version` is empty.' | ||
| value: ${{ steps.update.outputs.min-version }} | ||
| changed: | ||
| description: >- | ||
| `true` when a file was written, `false` when every header was already at its version, was | ||
| left above it, or no file carries one, so a later step can skip the commit. | ||
| value: ${{ steps.update.outputs.changed }} | ||
|
|
||
| runs: | ||
| using: 'composite' | ||
| steps: | ||
| - name: Update the WordPress version | ||
| id: update | ||
| uses: actions/github-script@v9 | ||
| env: | ||
| # github-script's require() resolves against the workspace of the repository being built, | ||
| # not this action's directory, so the path has to be passed in. github.action_path is the | ||
| # documented expression for it. | ||
| ACTION_PATH: ${{ github.action_path }} | ||
| # Read from process.env rather than interpolated into the script, so an input is data and | ||
| # never part of the program. | ||
| INPUT_TESTED_UP_TO: ${{ inputs.tested-up-to }} | ||
| INPUT_MIN_VERSION: ${{ inputs.min-version }} | ||
| INPUT_WORKING_DIRECTORY: ${{ inputs.working-directory }} | ||
| with: | ||
| script: | | ||
| const { runUpdateWpVersion } = require(`${process.env.ACTION_PATH}/update-wp-version.js`) | ||
| await runUpdateWpVersion({ core, env: process.env }) | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Because
tested-up-tois required, every repository has to add its own step that looks up the latest WordPress version first. LearnDash's script does that lookup itself:Could
tested-up-tokeep working as it does now, but default to the latest release from that endpoint when it's left empty? Passing a version would still win. If the lookup fails, the action should fail, the same as a malformed version does now.