Skip to content

Commit a8aa71b

Browse files
palickopalicko
committed
feat(codemods): add starter-2.1.1 migration (Acorn 6); release 0.3.0
First package-scoped migration (appliesTo.package: webentor-starter). Bumps the theme composer.json `roots/acorn` ^5.0 -> ^6.0 (Acorn 6 / Laravel 13) and syncs the root + theme changelogs (2.1.1). Does not bump webentor-core (^0.15 already covers the transparent 0.15.1 patch). The Acorn 6 .env changes (pin CACHE_PREFIX/SESSION_COOKIE/REDIS_PREFIX; rename MAIL_ENCRYPTION -> MAIL_SCHEME) are a documented manual step. - migrations/starter-2.1.1/{rules/deps.yml,changelog/{root,theme}.md,README.md} - migrations/__fixtures__/starter-2.1.1/{before,after,customized} - register in index.json; bump package 0.2.0 -> 0.3.0 + CHANGELOG - docs: add the migration row to upgrading/codemods.md Claude-Session: https://claude.ai/code/session_011LsRS3cybEkwuGfEpNET2y
1 parent 41410b8 commit a8aa71b

11 files changed

Lines changed: 350 additions & 1 deletion

File tree

‎docs/src/upgrading/codemods.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,7 @@ with the stack: it prepends the release's version block to the project root
7474
| --- | --- | --- |
7575
| `0.13.0` | core 0.12 → 0.13 | Moves the theme's `editor.css` + `button.style.css` enqueues from `enqueue_block_editor_assets` to a new `enqueue_block_assets` hook (`is_admin()` guarded) for WP 7.0's iframed editor; the editor JS stays put. Plus the full `package.json` + `composer.json` dependency bump set and changelog sync (2.0.7). |
7676
| `0.15.0` | core 0.13 → 0.15 | Vite 8 / Rolldown: `package.json` + `composer.json` dependency bumps, the `resources/scripts/app.ts` static-asset `import.meta.glob` fix, and changelog sync (2.1.0). The `vite.config.js` externals rewrite is a documented manual step (printed by the migration). |
77+
| `starter-2.1.1` | starter + theme 2.1.0 → 2.1.1 | Acorn 6 / Laravel 13: bumps `roots/acorn` to `^6.0` in the theme `composer.json` and syncs the root + theme changelogs (2.1.1). Does **not** bump `webentor-core`. The Acorn 6 `.env` changes (pin `CACHE_PREFIX`/`SESSION_COOKIE`/`REDIS_PREFIX`; rename `MAIL_ENCRYPTION` → `MAIL_SCHEME`) are a documented manual step. Select with `--package webentor-starter` for range runs. |
7778

7879
## Authoring a new migration
7980

‎packages/webentor-codemods/CHANGELOG.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,23 @@
11
# Webentor Codemods Changelog
22

3+
## 0.3.0
4+
5+
- Add the `starter-2.1.1` migration (theme **2.1.0 → 2.1.1**, **Acorn 6 / Laravel
6+
13**) — the first **package-scoped** migration (`appliesTo.package:
7+
webentor-starter`), selectable by id or `--package webentor-starter`. It does
8+
**not** bump `webentor-core`.
9+
- `deps.yml` (JSON): rewrites the theme's `composer.json` `roots/acorn` to `^6.0`.
10+
This is the complete dependency delta from the 2.1.0 baseline — `roots/acorn` is
11+
the only change; `webikon/webentor-core` stays `^0.15` (it already covers the
12+
transparent `0.15.1` patch). Scoped to `composer.json` (the project root
13+
`composer.json` has no `roots/acorn`), value-is-string guarded, idempotent.
14+
- Changelog sync prepends the `2.1.1` block to the project root `changelog.md`
15+
(marker `### 2.1.1`) and the theme `web/app/themes/*/changelog.md` (marker
16+
`### Version 2.1.1`), matching the coupled starter + theme `2.1.1` bump.
17+
- The Acorn 6 `.env` runtime changes (pin `CACHE_PREFIX`/`SESSION_COOKIE`/
18+
`REDIS_PREFIX` to preserve caches/sessions; rename `MAIL_ENCRYPTION` →
19+
`MAIL_SCHEME`) are a documented manual step (see the migration README).
20+
321
## 0.2.0
422

523
- **New capability — changelog sync.** A migration can now declare a `changelog`

‎packages/webentor-codemods/migrations/__fixtures__/starter-2.1.1/after/composer.json‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
{
2+
"name": "webikon/webentor-theme",
3+
"type": "wordpress-theme",
4+
"version": "2.1.0",
5+
"description": "Webentor starter theme",
6+
"homepage": "https://webikon.sk",
7+
"authors": [
8+
{
9+
"name": "Roots",
10+
"homepage": "https://github.com/roots/sage"
11+
},
12+
{
13+
"name": "Webikon s.r.o.",
14+
"email": "support@webikon.sk",
15+
"homepage": "https://webikon.sk"
16+
},
17+
{
18+
"name": "Pavol Caban",
19+
"email": "pavol.caban@webikon.sk",
20+
"homepage": "https://webikon.sk"
21+
}
22+
],
23+
"repositories": [
24+
{
25+
"type": "github",
26+
"url": "https://github.com/webikon/webentor-core.git"
27+
}
28+
],
29+
"autoload": {
30+
"psr-4": {
31+
"App\\": "app/"
32+
}
33+
},
34+
"require": {
35+
"php": ">=8.3",
36+
"johnbillion/extended-cpts": "^5.0",
37+
"log1x/acf-composer": "^3.0",
38+
"log1x/sage-directives": "^2.0",
39+
"log1x/sage-svg": "^2.0",
40+
"roots/acorn": "^6.0",
41+
"roots/acorn-prettify": "^1.0",
42+
"stoutlogic/acf-builder": "^1.12",
43+
"webikon/webentor-core": "^0.15"
44+
},
45+
"require-dev": {
46+
"squizlabs/php_codesniffer": "^3.8.0"
47+
},
48+
"config": {
49+
"optimize-autoloader": true,
50+
"preferred-install": "dist",
51+
"sort-packages": true
52+
},
53+
"minimum-stability": "dev",
54+
"prefer-stable": true,
55+
"scripts": {
56+
"post-autoload-dump": [
57+
"Roots\\Acorn\\ComposerScripts::postAutoloadDump"
58+
],
59+
"lint": [
60+
"phpcs --extensions=php --standard=PSR12 app"
61+
]
62+
}
63+
}

‎packages/webentor-codemods/migrations/__fixtures__/starter-2.1.1/before/composer.json‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
{
2+
"name": "webikon/webentor-theme",
3+
"type": "wordpress-theme",
4+
"version": "2.1.0",
5+
"description": "Webentor starter theme",
6+
"homepage": "https://webikon.sk",
7+
"authors": [
8+
{
9+
"name": "Roots",
10+
"homepage": "https://github.com/roots/sage"
11+
},
12+
{
13+
"name": "Webikon s.r.o.",
14+
"email": "support@webikon.sk",
15+
"homepage": "https://webikon.sk"
16+
},
17+
{
18+
"name": "Pavol Caban",
19+
"email": "pavol.caban@webikon.sk",
20+
"homepage": "https://webikon.sk"
21+
}
22+
],
23+
"repositories": [
24+
{
25+
"type": "github",
26+
"url": "https://github.com/webikon/webentor-core.git"
27+
}
28+
],
29+
"autoload": {
30+
"psr-4": {
31+
"App\\": "app/"
32+
}
33+
},
34+
"require": {
35+
"php": ">=8.3",
36+
"johnbillion/extended-cpts": "^5.0",
37+
"log1x/acf-composer": "^3.0",
38+
"log1x/sage-directives": "^2.0",
39+
"log1x/sage-svg": "^2.0",
40+
"roots/acorn": "^5.0",
41+
"roots/acorn-prettify": "^1.0",
42+
"stoutlogic/acf-builder": "^1.12",
43+
"webikon/webentor-core": "^0.15"
44+
},
45+
"require-dev": {
46+
"squizlabs/php_codesniffer": "^3.8.0"
47+
},
48+
"config": {
49+
"optimize-autoloader": true,
50+
"preferred-install": "dist",
51+
"sort-packages": true
52+
},
53+
"minimum-stability": "dev",
54+
"prefer-stable": true,
55+
"scripts": {
56+
"post-autoload-dump": [
57+
"Roots\\Acorn\\ComposerScripts::postAutoloadDump"
58+
],
59+
"lint": [
60+
"phpcs --extensions=php --standard=PSR12 app"
61+
]
62+
}
63+
}

‎packages/webentor-codemods/migrations/__fixtures__/starter-2.1.1/customized/composer.json‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
{
2+
"name": "acme/acme-theme",
3+
"type": "wordpress-theme",
4+
"version": "1.4.0",
5+
"description": "Acme project theme",
6+
"homepage": "https://acme.example",
7+
"authors": [
8+
{
9+
"name": "Acme s.r.o.",
10+
"email": "dev@acme.example",
11+
"homepage": "https://acme.example"
12+
}
13+
],
14+
"repositories": [
15+
{
16+
"type": "github",
17+
"url": "https://github.com/webikon/webentor-core.git"
18+
}
19+
],
20+
"autoload": {
21+
"psr-4": {
22+
"App\\": "app/"
23+
}
24+
},
25+
"require": {
26+
"php": ">=8.3",
27+
"johnbillion/extended-cpts": "^5.0",
28+
"log1x/acf-composer": "^3.4",
29+
"log1x/sage-directives": "^2.0",
30+
"log1x/sage-svg": "^2.0",
31+
"roots/acorn": "^6.0",
32+
"roots/acorn-prettify": "^1.0",
33+
"stoutlogic/acf-builder": "^1.12",
34+
"webikon/webentor-core": "^0.15",
35+
"wpackagist-plugin/safe-svg": "^2.2"
36+
},
37+
"require-dev": {
38+
"squizlabs/php_codesniffer": "^3.8.0"
39+
},
40+
"config": {
41+
"optimize-autoloader": true,
42+
"preferred-install": "dist",
43+
"sort-packages": true
44+
},
45+
"minimum-stability": "dev",
46+
"prefer-stable": true,
47+
"scripts": {
48+
"post-autoload-dump": [
49+
"Roots\\Acorn\\ComposerScripts::postAutoloadDump"
50+
],
51+
"lint": [
52+
"phpcs --extensions=php --standard=PSR12 app"
53+
]
54+
}
55+
}

‎packages/webentor-codemods/migrations/index.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,22 @@
3232
{ "entry": "changelog/theme.md", "target": "web/app/themes/*/changelog.md", "marker": "### Version 2.1.0" }
3333
],
3434
"docs": "README.md"
35+
},
36+
{
37+
"id": "starter-2.1.1",
38+
"title": "Upgrade consumer theme to Acorn 6 (Laravel 13) — theme 2.1.1",
39+
"description": "Starter/theme-only release (no webentor-core bump): bump roots/acorn ^5.0 -> ^6.0 (Acorn 6 / Laravel 13) in the theme composer.json. webentor-core stays ^0.15 (covers the transparent 0.15.1 patch). The Acorn 6 .env changes (CACHE_PREFIX/SESSION_COOKIE/REDIS_PREFIX pinning, MAIL_ENCRYPTION -> MAIL_SCHEME) are a documented manual step (see README).",
40+
"appliesTo": {
41+
"package": "webentor-starter",
42+
"from": "2.1.0",
43+
"to": "2.1.1"
44+
},
45+
"rules": ["rules/deps.yml"],
46+
"changelog": [
47+
{ "entry": "changelog/root.md", "target": "changelog.md", "marker": "### 2.1.1" },
48+
{ "entry": "changelog/theme.md", "target": "web/app/themes/*/changelog.md", "marker": "### Version 2.1.1" }
49+
],
50+
"docs": "README.md"
3551
}
3652
]
3753
}

‎packages/webentor-codemods/migrations/starter-2.1.1/README.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
# `starter-2.1.1` — upgrade a consumer theme to Acorn 6 (Laravel 13)
2+
3+
**Applies to:** consumer themes on the **2.1.0** baseline (webentor-core `0.15.x`).
4+
This is a **starter/theme-only** release — it does **not** bump `webentor-core`, so
5+
select it by id (or `--package webentor-starter`). Coming from an older baseline?
6+
Run the `0.15.0` core codemod first.
7+
8+
Run from your project root:
9+
10+
```sh
11+
pnpm dlx @webikon/webentor-codemods run starter-2.1.1 # preview (dry-run)
12+
pnpm dlx @webikon/webentor-codemods run starter-2.1.1 --apply # apply
13+
```
14+
15+
Then reinstall, rebuild, and clear caches:
16+
17+
```sh
18+
# in the theme dir
19+
composer update
20+
wp acorn optimize:clear
21+
```
22+
23+
This migration has **one automated rule** (a `composer.json` dependency bump) plus
24+
**manual `.env` steps** for the Acorn 6 runtime changes.
25+
26+
## 1. Dependency (`rules/deps.yml`, JSON)
27+
28+
Rewrites the theme's `roots/acorn` range to the **2.1.1 baseline** (`^6.0`). This is
29+
the complete delta from the 2.1.0 baseline — only `roots/acorn` changed.
30+
`webikon/webentor-core` stays `^0.15` (it already covers the transparent `0.15.1`
31+
patch), so it is intentionally absent here. The rule matches `roots/acorn` by its
32+
exact key (value-is-string guarded) and is scoped to `composer.json` via `files:`;
33+
the project root `composer.json` has no `roots/acorn`, so only the theme manifest
34+
matches.
35+
36+
| manifest | dependency | → range |
37+
|---|---|---|
38+
| composer.json | `roots/acorn` (major 5→6) | `^6.0` |
39+
40+
- **Idempotent:** re-running rewrites to the same range → no diff.
41+
- **Baseline caveat:** the fix pins `^6.0`, so a project already *ahead* within the
42+
major would be set back to it. Expected for a 2.1.0 → 2.1.1 upgrade.
43+
44+
After applying, run `composer update` to refresh `composer.lock`.
45+
46+
## 2. Acorn 6 runtime changes (manual `.env`)
47+
48+
Acorn 6 bundles Laravel 13. These are **not** codemodded — `.env` is project- and
49+
environment-specific — so apply them by hand on each environment:
50+
51+
- **Cache / session / Redis prefixes.** Laravel 13 changed the default prefix and
52+
cookie separators from underscores to hyphens. On an existing site this
53+
**invalidates the object cache and logs out every session** unless you pin the
54+
values explicitly:
55+
56+
```dotenv
57+
CACHE_PREFIX=your_existing_prefix
58+
SESSION_COOKIE=your_existing_cookie
59+
REDIS_PREFIX=your_existing_prefix
60+
```
61+
62+
A fresh project can ignore this (there is no cache/session to preserve).
63+
64+
- **Mail scheme.** If you set `MAIL_ENCRYPTION`, rename it to `MAIL_SCHEME`:
65+
66+
```diff
67+
- MAIL_ENCRYPTION=tls
68+
+ MAIL_SCHEME=smtps
69+
```
70+
71+
- **PHP floor.** Acorn 6 requires PHP `>=8.3` (already the theme's floor).
72+
73+
After any `.env` change, run `wp acorn optimize:clear`.
74+
75+
Reference: the starter theme's `composer.json` at theme 2.1.1, and the upstream
76+
[Acorn v6 upgrade notes](https://roots.io/acorn/docs/upgrading-acorn/).
77+
78+
## Changelog sync
79+
80+
Prepends the `2.1.1` version block to the project's changelogs so they match the
81+
stack:
82+
83+
- `changelog.md` (project root) ← `changelog/root.md` (marker `### 2.1.1`)
84+
- `web/app/themes/*/changelog.md` ← `changelog/theme.md` (marker `### Version 2.1.1`)
85+
86+
Idempotent (skipped if the heading is already present) and additive (inserted under
87+
the `# … Changelog` H1, above existing entries). If you've customized the changelog,
88+
your entries are preserved.
89+
90+
## Relationship to `update-dependencies`
91+
92+
This codemod only encodes the `roots/acorn` major as the released theme baseline.
93+
Routine third-party dependency maintenance (in-range patch/minor bumps) is a
94+
separate concern handled by the `update-dependencies` flow and is not part of a
95+
migration.

‎packages/webentor-codemods/migrations/starter-2.1.1/changelog/root.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
### 2.1.1
2+
3+
- Bump the bundled theme to `2.1.1` — `roots/acorn` to `^6.0` (from `^5.0`), i.e. **Acorn 6 / Laravel 13**.
4+
- **Requires consumer action on existing sites:** Laravel 13 changes the default cache-prefix / session-cookie / Redis-prefix separators (underscores → hyphens), which **invalidates the object cache and logs out all sessions** unless `CACHE_PREFIX`, `SESSION_COOKIE`, and `REDIS_PREFIX` are pinned in `.env`. Rename the SMTP `MAIL_ENCRYPTION` env var to `MAIL_SCHEME`. Acorn 6 requires PHP `>=8.3` (already the floor).
5+
- After upgrading, run `composer update` then `wp acorn optimize:clear`.
6+
- Bump `webentor-core` to `0.15.1` (transparent patch within the existing `^0.15` range: focal-point `<source srcset>` fix; no API change for consumers).
7+
- Existing projects can apply the `roots/acorn` bump via `pnpm dlx @webikon/webentor-codemods run starter-2.1.1`; the `.env` changes are a documented manual step in that codemod's README.

‎packages/webentor-codemods/migrations/starter-2.1.1/changelog/theme.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
### Version 2.1.1
2+
3+
- Bump `roots/acorn` to `^6.0` (from `^5.0`) — Acorn 6 ships Laravel 13 components.
4+
- **Breaking runtime behavior for existing sites:** Laravel 13 changes the default cache-prefix / session-cookie / Redis-prefix separators (underscores → hyphens), which **invalidates existing caches and logs out all sessions** unless `CACHE_PREFIX`, `SESSION_COOKIE`, and `REDIS_PREFIX` are pinned in `.env`. The SMTP `MAIL_ENCRYPTION` env var is renamed to `MAIL_SCHEME`. Requires PHP `>=8.3` (already the theme floor).
5+
- After upgrading, run `composer update` then `wp acorn optimize:clear` to rebuild Acorn's cached bootstrap files.
6+
- Bump `webentor-core` to `0.15.1` (within the existing `^0.15` range — no constraint change). Transparent patch: fixes focal-point cropping in responsive `<source srcset>` (no API change for consumers).
7+
- The `roots/acorn` bump is reproducible in existing projects via `pnpm dlx @webikon/webentor-codemods run starter-2.1.1`; the `.env` changes above are a manual step (documented in the codemod README).

‎packages/webentor-codemods/migrations/starter-2.1.1/rules/deps.yml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Dependency bump for the webentor-theme 2.1.1 upgrade (Acorn 6 / Laravel 13).
2+
#
3+
# Baseline = the 2.1.0 starter theme (webentor-core 0.15.x). This is the COMPLETE
4+
# `git diff starter-v2.1.0 -- <theme>/composer.json` dependency delta to the 2.1.1
5+
# baseline — only the `roots/acorn` major changed; everything else (including
6+
# `webikon/webentor-core ^0.15`, which already covers the transparent 0.15.1 patch)
7+
# carried over from 2.1.0 unchanged and is therefore absent here. Run the `0.15.0`
8+
# codemod first if coming from an older baseline.
9+
#
10+
# Same shape as the 0.15.0 deps rules: one rule per dependency, matched by its
11+
# exact key (anchored regex) with a value-is-string guard (so a config object that
12+
# shares a key is never clobbered), rewritten to the 2.1.1 baseline range
13+
# regardless of the consumer's current value. `files:` scopes the rule to
14+
# composer.json (the project root composer.json has no `roots/acorn`, so only the
15+
# theme manifest matches). `name`/`version` are never touched.
16+
id: deps-roots-acorn-composer
17+
language: json
18+
files: ['**/composer.json']
19+
rule:
20+
kind: pair
21+
all:
22+
- has: { field: key, regex: '^"roots/acorn"$' }
23+
- has: { field: value, kind: string }
24+
fix: '"roots/acorn": "^6.0"'

0 commit comments

Comments
 (0)