| name | update-phel |
| description | Bump phel-lang/phel-lang dependency to the latest release in this website repo. Triggers on "update phel", "bump phel", "upgrade phel-lang", "new phel release". Handles composer constraint bump, lock refresh, and verifies the post-update hook regenerated config.toml. |
| model | sonnet |
Update phel-lang to latest
This repo pins phel-lang/phel-lang in composer.json and mirrors the active version in config.toml (used by the Zola site to render the version badge / install snippets). A post-update-cmd runs build/update-phel-version.php which rewrites config.toml from the installed package version - do not edit config.toml by hand.
Procedure
-
Find current + latest version.
composer show phel-lang/phel-lang | grep -E "^versions"
composer show phel-lang/phel-lang --all | grep -E "^versions" | head -1
First command shows installed (marked *). Second lists all tags - latest stable is first non-dev-* entry.
-
Bump constraint in composer.json. Edit the phel-lang/phel-lang line under require. Use caret on the minor (^0.40), matching existing style. Phel is pre-1.0 so minor bumps may break - read the changelog if anything fails later.
-
Update lock + run post-update hook.
composer update phel-lang/phel-lang --with-dependencies
This pulls the new package, refreshes composer.lock, then auto-runs php build/update-phel-version.php which rewrites config.toml phel_version = "vX.Y.Z". If config.toml did NOT change, the hook failed - investigate before committing.
-
Verify.
git diff config.toml
composer test
composer test:snippets
composer test:snippets is the important one for a version bump: a new
Phel release can rename core fns, move namespaces, or change printed
output, which silently breaks documentation examples. The snippet baseline
(build/doc-snippets-baseline.json) is empty, so ANY newly-broken snippet
is reported as a regression and fails. See "When snippets break" below.
-
Scan prose for stale version strings. The snippet harness only runs ```phel blocks, so versions written in prose, JSON examples, and upgrade headings drift silently (they are never executed). After bumping to vX.Y.Z, grep for and update any that still name an older version:
grep -rnE '"phel-lang/phel-lang": *"\^0\.[0-9]+"|^## Upgrading|var-dumper' content/
Update at least:
content/documentation/installation.md - the ## Upgrading to ... heading, the composer require phel-lang/phel-lang:^X.Y command, and a short breaking-changes list for the new minor (pull from the release notes).content/documentation/guides/coming-from-clojure.md - the example composer.json pin.content/documentation/tooling/php-tools.md - the symfony/var-dumper constraint should match this repo's own composer.json.
These prose fixes belong in the same commit or a follow-up docs: commit.
-
Commit. Use this exact subject (matches prior chore: bump phel-lang to 0.39.0 convention):
chore: bump phel-lang to X.Y.Z
For a clean bump, stage exactly composer.json, composer.lock,
config.toml. If the new release added namespaces or broke snippets you
will also have legitimate changes to build/tests/.../ApiJsonFileTest.php,
content/**, and/or build/doc-snippets-baseline.json (see below) - those
belong in the SAME commit or a follow-up docs:/test: commit, not
discarded. Conventional commits, no Claude trailers (per global instructions).
Files touched (expected)
Clean bump (no API/snippet changes):
composer.json - constraint bump only (1 line)composer.lock - phel-lang + transitive deps (often symfony/*)config.toml - phel_version rewritten by post-update hook
A release that adds/renames core namespaces or changes runtime behaviour also
legitimately touches:
build/tests/php/ApiGenerator/Integration/ApiJsonFileTest.php - the
$expectedNamespaces list + its count (0.41 added edn, reflect, transit)content/documentation/reference/api/*.md - regenerated by composer buildcontent/** and build/doc-snippets-baseline.json - if doc snippets broke
When tests fail after bump
Phel < 1.0: minor releases can rename core fns or change emit output. Check:
https://github.com/phel-lang/phel-lang/releases/tag/vX.Y.Z for breaking changes- Failing tests in
build/tests/ - usually VersionUpdater or API page generation
- Regenerate API artifacts:
composer build (runs api-page.php, api-search.php, api-json.php, generate-releases.php)
If breakage is in Phel itself, do not patch the website to compensate - open an issue upstream and pin to the prior version.
When snippets break
composer test:snippets runs each ```phel doc block in content/ in an
isolated phel run subprocess against the new runtime. The baseline
(build/doc-snippets-baseline.json) is empty, so the suite is green only when
every block either passes or carries an explicit skip. A new release commonly
breaks blocks via renamed core fns, moved/renamed namespaces, or changed
printed output (; => comments). Triage each reported file:line [error]:
- Behaviour/name actually changed in Phel -> update the snippet to the new
API and fix any
; => output comment to the real runtime output (Phel
vectors print as @[...], strings keep quotes). This is the common case and
the whole point of the check.
- Genuinely non-runnable block (syntax template with placeholder ids, REPL
transcript, intentional-error demo, web/server-context) -> add an
<!-- phel-test: skip --> HTML comment on its own line directly above the
phel fence. Do NOT use a ` phel skip ` fence info string (breaks
syntax highlighting). Most templates are already skipped.
Iterate until composer test:snippets reports Failed: 0. Useful commands:
php build/run-doc-snippets.php content/path/to/file.md --verbose
php build/run-doc-snippets.php --update-baseline
Keep the baseline empty when possible - a non-empty baseline is debt, not a
solution.
