Repository navigation
Description
Why we need this
rtcamp/wp-framework is being renamed to rtcamp/wp-primitives in rtCamp/wp-primitives#98. The rename ships as v2.0.0 and moves the PHP namespace from rtCamp\WPFramework\ to rtCamp\WPPrimitives\. Class names stay the same.
Every PHP scaffold in @rtcamp/wp-tooling still targets the old name. Once 2.0.0 is out, a project on rtcamp/wp-primitives that runs wp-tooling add wp/cpt is told to install rtcamp/wp-framework:^1.0. The generated class also imports rtCamp\WPFramework\Contracts\Abstracts\AbstractPostType, which fails with "Class not found" because 2.x has no such namespace.
This issue moves wp-tooling to the new name everywhere it appears: scaffold manifests, templates, the setup skill, docs and tests.
Before you start
When this can merge
Work can start now. Merge only after rtCamp/wp-primitives#98 is merged, the GitHub repo is renamed to rtCamp/wp-primitives, and v2.0.0 is tagged. Before then, the rtcamp/wp-primitives:^2.0 dependency these scaffolds report will not resolve for consumers.
Worth reading first
- Rename rtcamp/wp-framework to rtcamp/wp-primitives wp-primitives#98: what the rename changes
docs/upgrading.mdin wp-primitives, section "1.0.x → 2.0.0": the consumer migration steps the CHANGELOG entry links tonode-packages/wp-tooling/AGENTS.md: rules for working in the package
The rename at a glance
| What | Old | New |
|---|---|---|
| Composer package | rtcamp/wp-framework |
rtcamp/wp-primitives |
| Version constraint | ^1.0 |
^2.0 |
| PHP namespace root | rtCamp\WPFramework\ |
rtCamp\WPPrimitives\ |
| Namespace inside JSON strings | rtCamp\\WPFramework\\ |
rtCamp\\WPPrimitives\\ |
| Repository URL | https://github.com/rtCamp/wp-framework |
https://github.com/rtCamp/wp-primitives |
| Vendor path | vendor/rtcamp/wp-framework/ |
vendor/rtcamp/wp-primitives/ |
Only the namespace root changes. For example, rtCamp\WPFramework\Contracts\Abstracts\AbstractPostType becomes rtCamp\WPPrimitives\Contracts\Abstracts\AbstractPostType.
What you're changing
All paths are relative to node-packages/wp-tooling/. To list every current hit (64 files), run this from the repo root:
grep -rnE 'wp-framework|WPFramework' node-packages/wp-tooling --exclude-dir=node_modules1. Scaffold manifests (scaffold.json, 22 files)
| Scaffolds | What to change |
|---|---|
wp/* (13): admin-page, block-dynamic, block-interactive, cli, cpt, cron, module, registrable, rest, settings-page, shortcode, taxonomy, user-role |
The composer_dependencies entry "rtcamp/wp-framework": "^1.0" becomes "rtcamp/wp-primitives": "^2.0". Also update any description that names the package, e.g. wp/cpt: "Adds a CPT class extending AbstractPostType from rtcamp/wp-framework." |
wp-api/* (3): block-bindings, script-module, speculation |
The composer_dependencies entry, same as above. |
utility/* (5): cache, feature-selector, logger, timer, transients |
The composer_dependencies entry, the description, the module_class (e.g. rtCamp\\WPFramework\\Utils\\Cache), and every class reference in the wiring[] entry. Each snippet names the class three times: the @return docblock, the method return type, and the new expression. |
lint/phpcs/full |
The composer_dev_dependencies entry and the description ("…via wp-framework."). |
2. Scaffold templates (templates/*.mustache, 33 files)
- Class and test templates of every
wp/*andwp-api/*scaffold above (32 files):use rtCamp\WPFramework\…;becomesuse rtCamp\WPPrimitives\…;- The file docblock line
@link https://github.com/rtCamp/wp-frameworkbecomes@link https://github.com/rtCamp/wp-primitives
lint/phpcs/full/templates/phpcs.xml.dist.mustache: the ruleset include<rule ref="vendor/rtcamp/wp-framework/phpcs.xml.dist"/>and the comment above it change tovendor/rtcamp/wp-primitives/phpcs.xml.dist. The file ships at the same path in 2.0.0.
3. Setup skill (2 files, keep them identical)
skills/setup/SKILL.mdand its bundled copyscaffolds/setup/claude-skills/templates/setup-SKILL.md, lines 135 and 338.- The two files are byte-identical today. Keep them that way.
4. Docs (4 files)
docs/wp-framework-contract.md: rename it todocs/wp-primitives-contract.mdwithgit mvso its history follows. Inside, update:- the title and intro (lines 1, 3 and 5)
- the history note (line 7). It should now say the package shipped as
rtcamp/wp-frameworkfor 1.0.x and was renamed tortcamp/wp-primitivesin 2.0.0. - the Composer coordinates block (line 15), to
"rtcamp/wp-primitives": "^2.0" - the namespace root (line 19)
- the three section intros that name the namespace (lines 37, 159 and 195)
- Links to the renamed file:
AGENTS.mdline 46 (the file tree) anddocs/authoring-scaffolds.mdline 427. docs/authoring-scaffolds.md: the exampleuseline (line 93), themodule_classexample (line 226), and the "When to involvewp-framework" section (lines 425–427). Its "open an issue onwp-framework" pointer should namertCamp/wp-primitives.docs/examples.md: the three references tortcamp/wp-framework:^1.0(lines 92, 356, 393).
5. Tests (1 file)
tests/scaffolds/bundled-manifests.test.js: lines 709, 717, 735 and 774 hard-code the old package, version and namespace. Update them to the new values.- Add a guard test in the same file that reads every file under
scaffolds/and fails if any of them matcheswp-frameworkorWPFramework. New scaffolds are usually started by copying an existing one, so a branch that predates this rename would otherwise bring the old name back without anyone noticing.
6. Changelog
- The existing
[Unreleased]entry forutility/*(line 13) namesrtcamp/wp-framework. It hasn't shipped yet, so update it in place. - Add a
### Changedsection under## [Unreleased]with a BREAKING entry: scaffolds now generate code forrtcamp/wp-primitives^2.0and thertCamp\WPPrimitives\namespace. Projects still onrtcamp/wp-framework^1.0must migrate first. Link to the wp-primitives upgrade guide.
Out of scope
- The generic word "framework" in prose, such as "the framework's Loader" or the
wp/moduledisplay name "Framework Module". These words describe what the package does, not its name, and wp-primitives' own docs still use them. - Projects that already contain code generated under the old name. The wp-primitives upgrade guide covers their migration.
- Consumer repos (features-plugin-skeleton, theme-elementary). The wp-primitives rollout in Rename rtcamp/wp-framework to rtcamp/wp-primitives wp-primitives#98 covers them.
Checked: nothing in wp-tooling depends on these
2.0.0 also changes the items below. They need no work here, because wp-tooling never references them:
- The asset handle prefix
wp-framework-(nowwp-primitives-) - The
wp-frameworktext domain (nowwp-primitives) - The AI rules file
framework-php.instructions.md(nowprimitives-php.instructions.md) - A Composer
repositoriesVCS entry. wp-tooling never writes one, so there's no URL to update.
How to verify your work
Run these from the repo root:
# Both must print nothing. CHANGELOG.md is excluded because the rename entry names the old package on purpose.
grep -rnE 'wp-framework|WPFramework' node-packages/wp-tooling --exclude-dir=node_modules --exclude=CHANGELOG.md
git ls-files node-packages/wp-tooling | grep wp-framework
# Must exit 0.
npm run checkQuick smoke test
This generates three scaffolds into a throwaway project and checks what they produce. Run it from the repo root:
SMOKE="$(mktemp -d)"
printf '{"name":"acme/demo","autoload":{"psr-4":{"Acme\\\\Demo\\\\":"inc/"}}}\n' > "$SMOKE/composer.json"
CLI=node-packages/wp-tooling/bin/wp-tooling.js
node "$CLI" add wp/cpt --cwd "$SMOKE" --json --slug=book --singular=Book --plural=Books > "$SMOKE/cpt.json"
node "$CLI" add utility/cache --cwd "$SMOKE" --json > "$SMOKE/cache.json"
node "$CLI" add lint/phpcs/full --cwd "$SMOKE" --json > "$SMOKE/phpcs.json"
# Must print nothing.
grep -rnE 'wp-framework|WPFramework' "$SMOKE"
# Must print "rtcamp/wp-primitives":"^2.0" twice (once for wp/cpt, once for utility/cache).
grep -hoE '"rtcamp/wp-primitives":"[^"]+"' "$SMOKE/cpt.json" "$SMOKE/cache.json"
# Must show the new namespace in the generated class.
grep -n 'WPPrimitives' "$SMOKE/inc/PostTypes/Book.php"On main today, the first grep lists six files (cpt.json, cache.json, phpcs.json, Book.php, BookTest.php, phpcs.xml.dist) and the last two print nothing.
Acceptance criteria
Runtime behavior
- Every
wp/*,wp-api/*andutility/*scaffold reportsrtcamp/wp-primitives: ^2.0as its Composer dependency. - Generated PHP classes and tests import from
rtCamp\WPPrimitives\and link tohttps://github.com/rtCamp/wp-primitives. -
utility/*wiring snippets build\rtCamp\WPPrimitives\Utils\…classes. -
lint/phpcs/fullno longer referencesrtcamp/wp-framework, in its dependency or in its renderedphpcs.xml.dist. - The smoke test above prints what it says it must.
Code quality
- Both repo-wide checks above print nothing.
-
npm run checkpasses. - The guard test fails when any file under
scaffolds/mentions the old name.
Docs
-
docs/wp-framework-contract.mdis renamed todocs/wp-primitives-contract.md, and every link to it is updated. -
skills/setup/SKILL.mdandscaffolds/setup/claude-skills/templates/setup-SKILL.mdare updated and still identical.
Housekeeping
-
CHANGELOG.mdhas a BREAKING entry under## [Unreleased], and the existingutility/*entry uses the new name.
Blocked by (for merge): rtCamp/wp-primitives#98
Activity