Docs: Add ESLint v10 migration guide and polish docs by manzoorwanijk · Pull Request #77217 · WordPress/gutenberg

manzoorwanijk · 2026-04-10T03:15:41Z

Summary

Part of #76506 (Phase 7 — Documentation, migration guide, changelog, announcements).

A follow up to #76654 and #77215

Add a comprehensive consumer migration guide at docs/how-to-guides/eslint-v10-migration.md covering flat config migration steps, rule prefix changes, wp-scripts updates, eslintrc compatibility wrapper usage, and troubleshooting
Polish packages/eslint-plugin/README.md: add minimum ESLint version note, expand eslintrc compat wrapper section, add rule prefix change and eslint-env removal to migration steps
Update packages/scripts/README.md lint-js section with breaking change notes for ESLint v10
Add PR links (Upgrade ESLint to v10 #76654) to all unreleased changelog entries in both eslint-plugin and scripts

Corresponding announcements (#core-js Slack, Make/Core blog post) will follow once this lands.

Test plan

Verify all links in the migration guide resolve correctly
Verify PR links in changelogs point to the correct PR
Review migration guide examples for accuracy against the current plugin API

Add a comprehensive consumer migration guide at docs/how-to-guides/eslint-v10-migration.md covering flat config migration, rule prefix changes, wp-scripts updates, and the temporary eslintrc compatibility wrapper. Polish eslint-plugin and scripts READMEs with minimum version requirements, expanded compat wrapper docs, and breaking change notes. Add PR links to all unreleased changelog entries.

github-actions · 2026-04-10T03:15:52Z

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: manzoorwanijk <[email protected]>
Co-authored-by: tyxla <[email protected]>
Co-authored-by: aduth <[email protected]>

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

github-actions · 2026-04-10T03:15:53Z

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

Required label: Any label starting with [Type].
Labels found: .

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.

manzoorwanijk · 2026-04-10T03:23:45Z

@jsnajdr @aduth @tyxla

Here are the drafts I am planning to share once this and #77215 land

Slack (#core-js)

📢 ESLint v10 Upgrade Landing in Gutenberg

We've upgraded @wordpress/eslint-plugin and @wordpress/scripts to ESLint v10 with flat config support. Here's what you need to know:

What changed:

@wordpress/eslint-plugin now exports flat config arrays (not eslintrc objects)
Minimum ESLint version: ^9.0.0 || ^10.0.0
@typescript-eslint/* upgraded from v6 to v8
eslint-comments/* rules renamed to @eslint-community/eslint-comments/*
wp-scripts lint-js defaults to flat config detection

For consumers extending @wordpress/eslint-plugin:

// OLD (.eslintrc.js)
module.exports = {
	extends: [ 'plugin:@wordpress/eslint-plugin/recommended' ],
};

// NEW (eslint.config.mjs)
import wordpress from '@wordpress/eslint-plugin';
export default [ ...wordpress.configs.recommended ];

Not ready to migrate? A temporary eslintrc compatibility wrapper is available for ESLint v9:

const wordpress = require( '@wordpress/eslint-plugin/eslintrc' );
module.exports = wordpress.configs.recommended;

This wrapper is deprecated and will be removed in a future major version.

Migration guide: Migration guide

Questions? Drop them in this thread.

Make Core

Migrating to ESLint v10 with `@wordpress/eslint-plugin`

Introduction

ESLint v10 drops the legacy eslintrc format entirely
@wordpress/eslint-plugin has been updated to export flat config arrays
This post covers what changed and how to migrate your project

What Changed

Flat config is the default — ESLint v10 only supports eslint.config.* files
Plugin exports — @wordpress/eslint-plugin now exports flat config arrays via wordpress.configs.recommended, wordpress.configs.esnext, etc.
Rule prefix change — eslint-comments/* → @eslint-community/eslint-comments/*. Update any inline /* eslint-disable eslint-comments/... */ comments.
TypeScript — @typescript-eslint/* upgraded from v6 to v8 via the unified typescript-eslint package
wp-scripts lint-js — Now detects flat config files first. Default config path changed from config/.eslintrc.js to config/eslint.config.cjs. Legacy .eslintrc.* fallback is deprecated.

Migration Steps

Replace .eslintrc.* with eslint.config.mjs
Convert extends to import + spread
Convert overrides to flat config objects with files
Replace env with languageOptions.globals (using globals npm package)
Move .eslintignore patterns to ignores config array
Update inline comments referencing old rule prefixes
Remove /* eslint-env */ comments (not supported in ESLint v10)

Temporary Compatibility Wrapper

For ESLint v9 users not ready to migrate: @wordpress/eslint-plugin/eslintrc
Deprecation timeline: will be removed in the next major version
Recommend migrating to flat config as soon as possible

For `wp-scripts` Users

wp-scripts lint-js auto-detects eslint.config.* files
If no flat config found, falls back to .eslintrc.* (deprecated)
Custom configs: migrate from config/.eslintrc.js to config/eslint.config.cjs

Resources

- Link to the new migration guide from eslint-plugin README - Add upstream ESLint v9 and v10 migration guide links - Add a TL;DR of breaking changes by ESLint version (v8→v9, v9→v10)

github-actions · 2026-04-16T12:50:19Z

Flaky tests detected in 4c15343.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/24509800151
📝 Reported issues:

[Flaky Test] post title and content are editable and blocks can be inserted #76524 in /test/e2e/specs/editor/various/post-content-focus-mode.spec.js
[Flaky Test] should show correct homepage actions based on current homepage or posts page #77385 in /test/e2e/specs/site-editor/homepage-settings.spec.js

manzoorwanijk · 2026-04-20T05:56:30Z

The package is out but the docs are not. I think we need to wrap this up ASAP.

aduth

This will be a very useful resource for folks looking to upgrade 👍

manzoorwanijk · 2026-04-20T13:25:09Z

@aduth Thank you for the review. What do you think about the announcement posts as mention in #77217 (comment) above?

* Docs: Add ESLint v10 migration guide, polish READMEs and changelogs Add a comprehensive consumer migration guide at docs/how-to-guides/eslint-v10-migration.md covering flat config migration, rule prefix changes, wp-scripts updates, and the temporary eslintrc compatibility wrapper. Polish eslint-plugin and scripts READMEs with minimum version requirements, expanded compat wrapper docs, and breaking change notes. Add PR links to all unreleased changelog entries. * Docs: Address PR review feedback - Link to the new migration guide from eslint-plugin README - Add upstream ESLint v9 and v10 migration guide links - Add a TL;DR of breaking changes by ESLint version (v8→v9, v9→v10) Co-authored-by: manzoorwanijk <[email protected]> Co-authored-by: tyxla <[email protected]> Co-authored-by: aduth <[email protected]>

manzoorwanijk requested review from ajitbohra, fabiankaegy, gziolo, juanmaguitar, nerrad, ntwb and ryanwelcher as code owners April 10, 2026 03:15

manzoorwanijk self-assigned this Apr 10, 2026

manzoorwanijk requested review from aduth and jsnajdr April 10, 2026 03:16

manzoorwanijk added the [Type] Developer Documentation Documentation for developers label Apr 10, 2026

WordPress deleted a comment from github-actions Bot Apr 10, 2026

tyxla reviewed Apr 10, 2026

View reviewed changes

Comment thread packages/eslint-plugin/README.md

Comment thread docs/how-to-guides/eslint-v10-migration.md

manzoorwanijk force-pushed the update/eslint/docs branch from 342a8a3 to 803e60e Compare April 10, 2026 12:31

Docs: Address PR review feedback

b3c038e

- Link to the new migration guide from eslint-plugin README - Add upstream ESLint v9 and v10 migration guide links - Add a TL;DR of breaking changes by ESLint version (v8→v9, v9→v10)

WordPress deleted a comment from github-actions Bot Apr 13, 2026

Merge branch 'trunk' into update/eslint/docs

4c15343

manzoorwanijk mentioned this pull request Apr 16, 2026

ESLint: Consolidate config into tools/eslint/ workspace package #77215

Merged

aduth approved these changes Apr 20, 2026

View reviewed changes

Comment thread packages/scripts/README.md

manzoorwanijk merged commit bbebe59 into trunk Apr 20, 2026
42 of 44 checks passed

manzoorwanijk deleted the update/eslint/docs branch April 20, 2026 13:23

github-actions Bot added this to the Gutenberg 23.1 milestone Apr 20, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: Add ESLint v10 migration guide and polish docs#77217

Docs: Add ESLint v10 migration guide and polish docs#77217
manzoorwanijk merged 3 commits into
trunkfrom
update/eslint/docs

manzoorwanijk commented Apr 10, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 10, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 10, 2026

Uh oh!

manzoorwanijk commented Apr 10, 2026

Migrating to ESLint v10 with `@wordpress/eslint-plugin`

Introduction

What Changed

Migration Steps

Temporary Compatibility Wrapper

For `wp-scripts` Users

Resources

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Apr 16, 2026

Uh oh!

manzoorwanijk commented Apr 20, 2026

Uh oh!

aduth left a comment

Uh oh!

Uh oh!

Uh oh!

manzoorwanijk commented Apr 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

manzoorwanijk commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

github-actions Bot commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Apr 10, 2026

Uh oh!

manzoorwanijk commented Apr 10, 2026

Migrating to ESLint v10 with @wordpress/eslint-plugin

Introduction

What Changed

Migration Steps

Temporary Compatibility Wrapper

For wp-scripts Users

Resources

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Apr 16, 2026

Uh oh!

manzoorwanijk commented Apr 20, 2026

Uh oh!

aduth left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

manzoorwanijk commented Apr 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

manzoorwanijk commented Apr 10, 2026 •

edited

Loading

github-actions Bot commented Apr 10, 2026 •

edited

Loading

Migrating to ESLint v10 with `@wordpress/eslint-plugin`

For `wp-scripts` Users