Skip to content

Add linting for PHP, patterns, and theme.json - #33

Merged
MaggieCabrera merged 4 commits into
WordPress:trunkfrom
troychaplin:add/lint-tooling
Sep 21, 2026
Merged

MaggieCabrera merged 4 commits into
WordPress:trunkfrom
troychaplin:add/lint-tooling

Conversation

@troychaplin

@troychaplin troychaplin commented Sep 16, 2026 •

Copy link
Copy Markdown
Member

Note

Part 1 of 3 in the lint stack. Please merge in this order:

  1. Add linting for PHP, patterns, and theme.json #33 Add linting for PHP, patterns, and theme.json (this PR)
  2. Add husky pre-commit to lint staged files #40 Add husky pre-commit to lint staged files
  3. Fix the PHPCS and theme validation errors #42 Fix the PHPCS and theme validation errors

The Lint checks fail here until #NN merges, so the three are best merged together.

Closes #10.

What

Adds linting for the theme and runs it in CI.

  • PHP: PHPCS with the WordPress Coding Standards and PHPCompatibilityWP, configured in composer.json and phpcs.xml.dist. The text domain and prefix are ipsum, and the minimum WordPress and PHP versions match style.css.
  • Patterns and theme.json: bin/validate-theme.mjs checks:
    • pattern headers: Title and Slug are present, the slug matches the file name, header keys are ones core reads, and categories are registered by core
    • block markup in patterns, templates, and parts: delimiters are balanced and attribute JSON is valid
    • wp:pattern and wp:template-part references point at files that exist
    • leftovers from editor exports named in the contributing guidelines: queryId, image id, template-part theme
    • visible text that isn't translatable
    • theme.json and the style variations against the schema for "Requires at least" (7.1), including the $schema value
  • CI: .github/workflows/lint.yml runs PHPCS and the validator on pull requests and on pushes to trunk. PHPCS results show as annotations on the PR.
  • Node 24.18+ and npm 11.16+, set the same way as in Gutenberg (Redo "Framework: Update Node.js to v24 LTS and npm to v11" gutenberg#82370): engines and devEngines in package.json, .nvmrc, and engine-strict in .npmrc.

Expected failures

This PR only adds the tooling, so both jobs fail on the current theme. #NN fixes all of these.

  • PHPCS: 233 errors across the 30 pattern files, 173 of them fixable with composer format. functions.php is clean.
  • $schema: 14 files aren't pinned to 7.1. Point the theme.json schema at trunk #27 and #NN make the same change.
  • queryId: 14 left over from editor exports.
  • theme.json: 6 null border values on core/accordion-heading and core/details.
  • Untranslatable text: "prefix":"Tags: " on wp:post-terms in single.php and single-sidebar.php.

Notes

  • Set up the development environment #16: it also adds package.json, package-lock.json, .gitignore, and .nvmrc. Whichever PR merges second combines them and regenerates the lock file with npm 11. Set up the development environment #16's .nvmrc (24) and engines.node (>=20) would move to the new minimums.
  • Raise the minimum PHP version to 7.4 #29: when it raises "Requires PHP" to 7.4, testVersion in phpcs.xml.dist should move to 7.4-.
  • Schema gap: the validator skips per-block spacing.blockGap written as a { top, left } object. Core supports that form, but the theme.json schema doesn't allow it yet.

Testing

With PHP, Composer, and Node 24.18+ (nvm use):

composer install
npm install
npm run lint:php
npm run lint:theme

Both commands should report the failures listed above.

🤖 Generated with Claude Code

@troychaplin

Copy link
Copy Markdown
Member Author

@juanfra @carolinan please let me know if this would be a good start point for linting in the theme and I am happy to cycle back, fix the issues and submit this as a proper PR.

@pattonwebz

pattonwebz commented Sep 16, 2026 •

Copy link
Copy Markdown
Member
Sniff Count Fixable Reported by
PEAR.Functions.FunctionCallSignature.SpaceAfterOpenBracket 53 yes WordPress-Core
PEAR.Functions.FunctionCallSignature.SpaceBeforeCloseBracket 53 yes WordPress-Core
Squiz.PHP.EmbeddedPhp.SpacingBeforeClose 53 yes WordPress-Core
Squiz.Commenting.FileComment.MissingPackageTag 30 no WordPress-Docs
Squiz.Commenting.FileComment.SpacingAfterComment 30 no WordPress-Docs
Squiz.PHP.EmbeddedPhp.ContentBeforeOpen / ContentAfterOpen / ContentBeforeEnd 9 yes WordPress-Core
Universal.CodeAnalysis.NoEchoSprintf 3 yes WordPress-Extra
Squiz.WhiteSpace.SuperfluousWhitespace.EndLine 2 yes WordPress-Core

The 60 that phpcbf cannot fix all come from WordPress-Docs: a @package tag and a blank line after the file comment, in each of the 30 pattern headers.

phpcs.xml.dist uses <rule ref="WordPress"/>, which is Core + Docs + Extra. Core applies only WordPress-Core to its own bundled themes: phpcs.xml.dist in wordpress-develop excludes src/wp-content/themes/(?!twenty)*, so Twenty Twenty-Five and the other twenty* themes are linted, but with Core alone. Their patterns are conformant under it like spaced inline PHP such as <?php esc_html_e( 'Comments', 'twentytwentyfive' ); ?>.

With <rule ref="WordPress-Core"/>, the count falls from 233 to 170, all of them auto-fixable, and phpcbf clears them all. Re-running bin/validate-theme.mjs afterwards reports the same 36 problems and no new ones, so the reformatting does not damage the block markup.

The alternative is to keep the full ruleset and add @package, @subpackage and @since to all 30 pattern headers by hand. Twenty Twenty-Five does carry those, so it is a legitimate choice, but none of the 60 edits are fixable by phpcbf, and they may sit better as a deliberate follow-up than as what stands between this pull request and a green job.

WordPress-Extra accounts for 3 of the violations, and phpcbf fixes those, so keeping it costs nothing; core simply does not apply it to themes either.

One fix not to trust phpcbf on

Three of the automatic fixes move inline PHP onto its own line inside a block, which changes the markup that ships:

  • patterns/footer.php:11-12, patterns/footer-wide.php:13-14, patterns/hero-epigraph.php:25-26
-<p class="has-manrope-font-family has-small-font-size"><?php /* Translators: … */
-echo sprintf( esc_html__( 'Designed with %1$sWordPress%2$s', 'ipsum' ), … ); ?></p>
+<p class="has-manrope-font-family has-small-font-size">
+<?php
+/* Translators: … */
+echo sprintf( esc_html__( 'Designed with %1$sWordPress%2$s', 'ipsum' ), … );
+?>
+</p>

The change is whitespace only and collapses in HTML, but it does alter rendered output, and both footer files carry trailing whitespace on the same lines. Writing those three as single-line inline PHP — Twenty Twenty-Five's style — satisfies the rule without touching the output.

The 36 problems from bin/validate-theme.mjs

14 theme-json-schema-version, 14 editor-leftovers (queryId), 6 theme-json-schema, 2 untranslated-text ("prefix":"Tags: ").

14 of them are #27. On the six null border values: the only place the published 7.1 schema allows null is settings.spacing.blockGap, where it further disables the control. Nothing under styles accepts it, so unlike the spacing.blockGap object the validator already skips, this is not a gap in one position of the styles tree. core/accordion-heading and core/details set "color": null, "style": null, "width": null alongside a real top border, which reads as deliberate, but it is worth confirming that core honours a null there before either relaxing the check or dropping the values. Twenty Twenty-Five's theme.json has no nulls at all.

CI consequence

The workflow also runs on pushes to trunk, so unless the fixes land with the tooling, trunk is red from the moment it merges. Landing the phpcbf commit alongside the tooling, or adding continue-on-error for a release or two, would keep the signal usable.

If we drop the WordPress-Docs ruleset a phpcbf pass plus the three rewritten lines gets a green linting pass and we can work to add the husky commit checking.

@troychaplin

Copy link
Copy Markdown
Member Author

@juanfra @carolinan please let me know if this would be a good start point for linting in the theme and I am happy to cycle back, fix the issues and submit this as a proper PR.

Just to avoid and working without lint tools I've moved ahead and to fixing the concerns and split the lint work into three PRs to keep each review small: this one (the tooling), #40 (the pre-commit hook), and #NN (fixes for everything the linters report). They need to merge in that order, ideally together, because the Lint checks fail until #42 lands. The order and links are at the top of each description.

@troychaplin
troychaplin marked this pull request as ready for review September 17, 2026 02:19
…ing (package.json, lock file regenerated with npm 11, .nvmrc kept at 24.18) and moved PHPCS to PHP 7.4 to match WordPress#29.
@github-actions github-actions Bot added documentation Improvements or additions to documentation [Type] Tooling Issues or PRs related to tooling GitHub Actions Pull requests that update GitHub Actions code labels Sep 17, 2026
@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: troychaplin <areziaal@git.wordpress.org>
Co-authored-by: MaggieCabrera <onemaggie@git.wordpress.org>
Co-authored-by: carolinan <poena@git.wordpress.org>
Co-authored-by: pattonwebz <williampatton@git.wordpress.org>
Co-authored-by: juanfra <juanfra@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

@troychaplin

Copy link
Copy Markdown
Member Author

This change overlaps with #60 — we both bump Node and NPM to the same versions.

@carolinan carolinan left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not the best person to review this, I rarely set up these things from scratch, but I'd like us to move forward ;)

@MaggieCabrera

MaggieCabrera commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

Some things: we should add stylelint since we have CSS in the theme (we'll see how much we can remove but we have it so we need it) and we need to fix the failures before landing this. The stylelint can happen on another PR

@carolinan

Copy link
Copy Markdown
Contributor

the failures are fixed in #42 right?

@troychaplin

troychaplin commented Sep 21, 2026 •

Copy link
Copy Markdown
Member Author

the failures are fixed in #42 right?

Yes that's corret @carolinan, lint issues in #33 and #40 are fixed in #42

@troychaplin

troychaplin commented Sep 21, 2026 •

Copy link
Copy Markdown
Member Author

Some things: we should add stylelint since we have CSS in the theme (we'll see how much we can remove but we have it so we need it) and we need to fix the failures before landing this. The stylelint can happen on another PR

Happy to add an issue and related PR for this @MaggieCabrera. But would it be easier to finish #33, #40, then #42 first?

MaggieCabrera and others added 2 commits September 21, 2026 13:10
Match Requires PHP in style.css after WordPress#29.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@MaggieCabrera
MaggieCabrera merged commit 27d6918 into WordPress:trunk Sep 21, 2026
2 of 4 checks passed
josephscott added a commit to josephscott/ipsum that referenced this pull request Sep 21, 2026
MaggieCabrera pushed a commit to josephscott/ipsum that referenced this pull request Oct 20, 2026
MaggieCabrera pushed a commit to josephscott/ipsum that referenced this pull request Nov 3, 2026
MaggieCabrera pushed a commit to josephscott/ipsum that referenced this pull request Nov 9, 2026
MaggieCabrera added a commit that referenced this pull request Nov 9, 2026
* Provide style.min.css for production

Using the same pattern as the TT5 theme - https://themes.trac.wordpress.org/browser/twentytwentyfive/1.5/package.json - this change adds a `style.min.css` and the tooling around it to build it.

The `style.css` file would still be used any time that `SCRIPT_DEBUG` is true - which is the case for the `wp-env` setup used by Ipsum.  Production setups would get the benefit of using the smaller `style.min.css` file.

For sizes, `style.min.css` comes in at 3,354 bytes.  Down from the 9,380 bytes of `style.css`.  Here are a few quick compression numbers:

- `gzip -5 style.min.css` : 1,134 bytes
- `brotli -5 style.min.css` : 996 bytes
- `zstd -8 style.min.css` : 1,142 bytes

The original `style.css` compressed at the same rates is still larger:

- `gzip -5 style.css` : 3,727 bytes
- `brotli -5 style.css` : 3,426 bytes
- `zstd -8 style.css` : 3,701 bytes

This is an improvement across the board, and doesn't change the ability to run the theme without having to touch a build system.

* Use style.css if it is newer than style.min.css

* Bump to the latest versions of cssnano and postcss-cli

This is possible now that #33 has been merged

* Skip the generated style.min.css in Stylelint

The minified stylesheet can't follow the WordPress CSS Coding Standards,
so `npm run lint:css` would fail on it. The pre-commit hook passes staged
files to Stylelint by name, so it also needs --allow-empty-input for a
commit that only rebuilds style.min.css.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Rebuild style.min.css after rebasing onto trunk

style.css changed on trunk since style.min.css was built, including the
palette rename in #179, so the old minified file pointed at color slugs
that no longer exist.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Document the style.min.css build step for agents

AGENTS.md still said there is no build step, and that style.css loads on
the front end. CONTRIBUTING.md called style.css the only stylesheet,
which stopped being true when assets/css/editor-style.css landed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Fail CI when style.min.css is out of date

style.min.css is committed, so nothing stopped a pull request from
changing style.css without rebuilding it. The CSS job now rebuilds it
and fails if the result differs from the committed copy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Rebuild style.min.css in the pre-commit hook

Contributors no longer need to remember npm run build when they change
style.css, and the CI check should rarely fail. Stylelint isn't repeated
in the new task because the *.css task already runs it on style.css.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Rebuild style.min.css for trunk's latest style.css

Trunk changed style.css in #180 and #198 after this branch was last
rebuilt, so the CI check failed on the merge with trunk.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: MaggieCabrera <maggie.cabrera@automattic.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: josephscott <josephscott@git.wordpress.org>
Co-authored-by: MaggieCabrera <onemaggie@git.wordpress.org>
Co-authored-by: mikachan <mikachan@git.wordpress.org>
Co-authored-by: carolinan <poena@git.wordpress.org>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation GitHub Actions Pull requests that update GitHub Actions code [Type] Tooling Issues or PRs related to tooling

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add linting for patterns and the theme

4 participants