Docs: Add ESLint v10 migration guide and polish docs

[manzoorwanijk]

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

[github-actions]

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 <manzoorwanijk@git.wordpress.org>
Co-authored-by: tyxla <tyxla@git.wordpress.org>
Co-authored-by: aduth <aduth@git.wordpress.org>

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

[github-actions]

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]

@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

1. Replace .eslintrc.* with eslint.config.mjs
2. Convert extends to import + spread
3. Convert overrides to flat config objects with files
4. Replace env with languageOptions.globals (using globals npm package)
5. Move .eslintignore patterns to ignores config array
6. Update inline comments referencing old rule prefixes
7. 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

• ESLint flat config migration guide
• @wordpress/eslint-plugin README
• Full migration guide in Gutenberg docs

[github-actions]

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]

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]

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