Releases and previews
A release is a tarball, its checksum and a version index, built by tools/release.php. Tags build releases; pushes to the sdk branch build previews until 2.0.0 is out.
Releases are immutable: a published version is never rebuilt with different contents, a fix is a new version.
tools/release.php enforces it, and the workflows call it.
tools/release.php
| Argument | Meaning |
|---|---|
version |
X.Y.Z, or X.Y.Z-alpha1, -beta1, -RC1 (a dot before the number is accepted: 2.0.0-alpha.7). A leading v is dropped. Anything else is refused. |
outdir |
Where the three assets are written; created if missing. |
--index-url |
The previous index.json to merge: an http(s) URL, a file:// URL or a path. Default: <outdir>/index.json when it exists. A missing file or an HTTP 404 means a first release; any other failure stops the script. |
--base-url |
Where the tarball will be downloaded from; the index entry is <base-url>/<tarball>. Default: the bare file name, relative to the index. |
It writes:
| File | Content |
|---|---|
php-esp32-sdk-<version>.tar.gz |
The tarball, with everything under one directory, php-esp32-sdk-<version>/. |
SHA256SUMS |
The sha256 of the tarball, in sha256sum format. |
index.json |
{"name": "esp32", "versions": {"<version>": {"url", "sha256"}}}, sorted by version. |
What is packaged
The tarball holds a fixed list of top-level entries; the rest of the repository stays out.
| Packaged | Not packaged |
|---|---|
sdk.json, LICENSE, README.md, driver, php, chips, boards, runtimes, storages, networks, host, sources |
tests, tools, vendor, composer.json, composer.lock, phpunit.xml.dist, assets, docs, AI_USAGE.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md, CHANGELOG.md |
Any top-level file or directory that is in neither list (dot entries aside) stops the script with unknown top-level entry. Add it to PACKAGED or UNPACKAGED in tools/release.php. Symbolic links, __pycache__,
.pyc files and dot files inside packaged directories are never included, and a symlink is an error.
Version, contents and reproducibility
sdk.jsonin the repository carries a placeholder version. The script writes the release version into the packaged copy only, without reformatting the file, and checks that nothing else changed.- With
vendor/installed, it loads the packaged tree with the specSdkLoaderand printsvalidated: <n> boards, <m> chips, PHP <minors>; a tree that does not load is an error. Withoutvendor/it warns and skips the check, so runcomposer installfirst. - The tarball is reproducible: files sorted, fixed owner, the modification time from
SOURCE_DATE_EPOCH, else the last commit time, else 0. The CI setsSOURCE_DATE_EPOCHto the commit time.
The index and immutability
The previous index is read and the new version is added to it. If the version is already there with a
different sha256, the script stops with version <v> is already in <index> with another sha256: releases are immutable, use a new version; with the same sha256 the run is idempotent. Relative URLs of a previous index
read from somewhere else (another directory, an URL) are made absolute, so they stay valid in the new file.
release.yml
.github/workflows/release.yml runs when a tag matching v[0-9]+.[0-9]+.[0-9]+* is pushed.
- tag: the tag must be semver,
vX.Y.ZorvX.Y.Z-alphaN,-betaN,-RCN, which Composer and Packagist accept; anything else fails the run. - tests: the
tests.ymlmatrix, against the spec tag inSPEC_REF. - release: checks out the SDK and
php-baremetal/spec, installs PHP 8.4 and the dependencies, then:- downloads
index.jsonof the latest release (releases/latest). Without a release, or with a latest release that has noindex.json(the releases before the SDK, v1.5.0 and older, carry none), it starts a new index; any other API error fails the run; - runs
tools/release.phpwith the tag without itsv,--index-url previous/index.jsonand--base-url https://github.com/<repository>/releases/download/<tag>; - publishes
php-esp32-sdk-*.tar.gz,SHA256SUMSandindex.jsonto the GitHub release of the tag, with generated release notes. A tag with a-is a prerelease and is not made the latest release; any other tag is, soreleases/latest/download/index.jsonalways lists every stable version.
- downloads
SPEC_REF in release.yml is the php-baremetal/spec tag the release is built and tested against. It
appears twice, in the env block and as the spec-ref of the tests job: set both to the released spec tag
before you tag the SDK.
To release: make sure the tests pass on master, set SPEC_REF, then tag and push.
preview.yml
Until 2.0.0 is released, every push to the sdk branch (and a manual run) publishes a preview. phpbm reads
these previews by default, so esp32@^2.0 resolves to them.
- The tests run first, against
SPEC_REF. - The version is
2.0.0-alpha.<run number>of the workflow. - The previous
index.jsonis downloaded from thesdk-previewrelease when it exists, andtools/release.phpmerges the new version into it with--base-urlpointing atreleases/download/sdk-preview: the index lists every preview so far, and each tarball stays downloadable. - The assets go to the
sdk-previewpre-release, never the latest one, namedSDK preview (latest <version>). - Runs are serialised (
concurrency: preview, no cancelling), so two pushes cannot overwrite each other's index.
Once v2.0.0 is out, delete .github/workflows/preview.yml and the sdk-preview release; the default index of
phpbm moves back to releases/latest/download/index.json.
How phpbm reads the index
phpbm reads index.json from the pattern https://github.com/php-baremetal/php-{name}-sdk/releases/download/sdk-preview/index.json
(the previews; after 2.0.0, releases/latest/download/index.json), with {name} the SDK name. It picks the
highest version that satisfies the project's constraint, downloads the url, checks the sha256, and
unpacks it into ~/.phpbm/sdks/esp32/<version>. PHPBM_SDK_INDEX replaces the pattern, and accepts a local path or a
file:// URL; a relative url in the index is resolved against the index's own location.
Testing a release locally
Build the assets into a directory, point phpbm at the index there, and install from it.
Pick a version that is not in the public index, or phpbm may prefer the published one: the highest version
wins. Remove the installed copy with phpbm sdk:remove [email protected] when you are done. To try the
working tree without a tarball, use phpbm sdk:link instead, see
Working on the SDK.