Published under Storytime

ESLint v9.0.0：回顾

自从 ESLint v9.0.0 发布已经超过一年了。在这篇文章中，我们回顾了哪些做得好，哪些不尽如人意，以及我们学到了什么。

2024年4月，我们发布了 ESLint v9.0.0，这是我们近三年来的第一次重大版本发布。v9.0.0 的主要功能是新的配置系统，在开发过程中收到了积极的评价。虽然我们预期发布会顺利，但事实很快证明发布过程充满挑战。最初的在线反馈总体上是负面的，用户表示 v9.0.0“还没准备好”、“不起作用”，甚至“破坏了生态系统”。一些人推迟了升级，而另一些人则考虑完全更换工具。对于团队和社区来说，这一经历都令人沮丧。现在，已经过去一年多，我们正在反思哪些做得好，哪些做得不好，以及我们从中学到了什么。

🌐 In April 2024, we released ESLint v9.0.0, our first major release in nearly three years. The key feature of v9.0.0 would be the new configuration system, which had received positive reviews while in development. While we anticipated a smooth launch, the release quickly proved challenging. Initial online sentiment was largely negative, with users saying v9.0.0 “wasn’t ready,” “didn’t work,” or even “broke the ecosystem.” Some postponed upgrading, while others considered switching tools altogether. The experience was frustrating for both the team and the community. Now, more than a year later, we’re reflecting on what went well, what didn’t, and what we’ve learned.

时间线

🌐 Timeline

为了提供背景信息，这里是 v9.0.0 开发的时间线，从新配置系统的初步设计到其正式发布。

🌐 To provide context, here’s a timeline of v9.0.0’s development, from the initial design of the new configuration system to its production release.

新配置系统的开发历时五年多，从最初的 RFC 到最终发布。API 预览版本在 2022 年 8 月 1 日的 v8.21.0 发布，随后在 2022 年 8 月 26 日的 v8.23.0 发布了 CLI 预览版本，使用户能够选择使用平面配置。此后，我们继续完善该系统，修复漏洞并优化设计。我们认为配置系统在 ESLint v8.45.0（2023 年 7 月 14 日发布）中功能完整。这为其在 ESLint v9.0.0（2024 年 4 月 5 日发布）中成为默认配置奠定了基础。以下是该时间线上的一些关键统计数据：

🌐 The development of the new configuration system spanned more than five years, from the initial RFC to the final release. The API preview shipped in v8.21.0 on August 1, 2022, followed by the CLI preview in v8.23.0 on August 26, which allowed users to opt in to flat config. From there, we continued refining the system, fixing bugs and smoothing out the design. We considered the configuration system feature complete with ESLint v8.45.0, released on July 14, 2023. That set the stage for it to become the default in ESLint v9.0.0 on April 5, 2024. Here are a few key stats from that timeline:

  • 从最初的平面配置 RFC 到最终发布，几乎经过了 五年 的时间
  • 在 v9.0.0 之前，命令行接口中可以使用扁平配置长达 20 个月
  • 在 v9.0.0 发布之前，Flat 配置已经功能完整 八个月
  • 在四个月内进行了七次预发布，默认配置为平面配置

做对了什么

🌐 What went right

以下是 v9.0.0 版本按计划进行的内容。

🌐 Here’s what went according to plan with the v9.0.0 release.

正式制定版本支持政策；与 HeroDevs 合作

🌐 Formalizing a version support policy; partnered with HeroDevs

我们首次为较旧的 ESLint 版本正式制定了一个版本支持政策。这一政策源于与HeroDevs关于永无止境的支持的讨论。他们强调明确说明旧版本将获得何种支持以及支持何时结束的重要性。在过去，对前一个主版本的支持会立即停止，但这一点未被记录。随着 v9.0.0 变更范围的增大，我们认识到这种做法会造成过大的干扰。

🌐 For the first time, we formalized a version support policy for older ESLint releases. This stemmed from discussions with HeroDevs about never-ending support. They emphasized the importance of clearly stating what support older releases would receive and when it would end. In the past, support for the previous major version was cut off immediately, but this was undocumented. With the scope of changes in v9.0.0, we recognized that approach would be too disruptive.

将修复回移到 v8.x

🌐 Backporting fixes to v8.x

在 v9.0.0 发布后，我们对 v8.x 版本线进行了六个月的支持，回移了与新配置系统相关的错误修复和兼容性更新。此后，HeroDevs 接管了 v8.x 及更早版本的维护工作。

🌐 We supported the v8.x release line for six months after the v9.0.0 release, backporting bug fixes and compatibility updates related to the new configuration system. After that, HeroDevs took over maintenance of v8.x and earlier versions.

这是我们第一次同时支持两个发布分支。这要求我们彻底改造基础设施，以支持从多个分支发布，而不仅仅是 main。我们还更新了首页，以清楚地显示哪个版本是稳定版，哪个版本是预发布版。

🌐 This was the first time we supported two release lines simultaneously. It required overhauling our infrastructure to support publishing from multiple branches, not just main. We also updated the homepage to clearly show which release was stable and which was in prerelease.

文档与沟通

🌐 Documentation and communication

我们为 v9.0.0 版本制作了大量文档，包括博客文章和迁移指南。在许多方面，这是迄今为止文档最完整的 ESLint 版本。我们还引入了一个新流程：v9.0.0 迁移指南 会在每个新功能的拉取请求中更新。之前，我们是在所有功能合并之后才编写指南，这增加了遗漏的可能性。这个新方法有助于确保没有遗漏任何内容。

🌐 We produced extensive documentation for the v9.0.0 release, including blog posts and migration guides. In many ways, it was the most thoroughly documented ESLint release to date. We also introduced a new process: the v9.0.0 migration guide was updated in the same pull request as each new feature. Previously, we wrote the guide after all features had been merged, increasing the chance of omissions. This new approach helped ensure nothing was missed.

预料并应对混乱

🌐 Expecting and responding to the chaos

根据以往的经验，我们知道迁移到一个主要版本通常是一个缓慢而困难的过程。尽管进行了广泛的测试，我们仍然预期会出现问题。当事情不能立即运行时，用户通常会推迟升级，直到他们有时间进行调查。这个模式在每一个主要的 ESLint 版本中都得到了验证。

🌐 From past experience, we knew that migrating to a major release is often a slow and difficult process. Despite extensive testing, we expected issues. When things don’t work immediately, users typically delay upgrades until they have time to investigate. This pattern has held true for every major ESLint release.

我们预期会收到大量的早期反馈，这最终促成了像 兼容性工具、配置检查器 和 配置迁移工具 这样的工具的发布。团队反应迅速且建设性，即使是批评性的反馈也不例外。这些努力现在正在得到回报，因为新的 ESLint v9.x 用户正在体验到更加顺畅的升级路径。

🌐 We anticipated a flood of early feedback, which ultimately led to the release of tools like the compatibility utilities, the Config Inspector, and the Config Migrator. The team responded quickly and constructively, even when feedback was critical. Those efforts are now paying off, as new adopters of ESLint v9.x are seeing a much smoother upgrade path.

出了什么问题

🌐 What went wrong

虽然我们为 ESLint v9.0.0 所取得的进展感到自豪，但在某些方面事情并没有按计划进行。

🌐 While we’re proud of the progress made with ESLint v9.0.0, there were areas where things didn’t go as planned.

太多重大变更

🌐 Too many breaking changes

最大的问题是将太多重大变更打包在一次大型版本发布中。一个关键的例子是同时引入新的配置系统和 规则 API 变更，这两者都是实现 语言插件 的必要步骤。这往往使得很难准确找出现有插件问题的原因。许多人认为问题在于新的配置系统，形成了一种“坏掉了”或“尚未准备好”的叙述。实际上，规则 API 的变更同样具有破坏性。

🌐 The biggest mistake was bundling too many breaking changes into a single major release. A key example was introducing the new configuration system alongside the rule API changes, both of which were necessary steps to enable language plugins. This often made it difficult to pinpoint the cause of issues with existing plugins. Many assumed the new configuration system was to blame, creating a narrative that it was “broken” or “not ready.” In reality, the rule API changes were just as disruptive.

我们太专注于配置系统的推出，以至于低估了规则 API 变更的影响。

🌐 We were so focused on the configuration system rollout that we underestimated the impact of the rule API changes.

文档太多，但工具不够

🌐 Too much documentation and not enough tooling

我们认为提供详尽的文档可以缓解预计的升级痛苦。我们发布了发行说明、v9.0.0迁移指南、配置迁移指南和插件迁移指南，相信已经涵盖了所有重要的更改。但我们没有预料到，对于大多数用户来说，这些文档会过于庞杂。

🌐 We thought that providing extensive documentation would ease the expected upgrade pain. We published release notes, a v9.0.0 migration guide, a configuration migration guide, and a plugin migration guide, believing we had covered all the important changes. What we didn’t anticipate was that this amount of documentation would be overwhelming for most users.

我们的假设是用户会先阅读发布说明，然后阅读迁移指南，最后安装 v9.0.0。相反，许多人直接安装了它，遇到了关于缺少配置文件的错误信息，然后才回过头来看文档寻求指导。许多用户在没有先阅读文档的情况下就去 Discord 或 GitHub 寻求帮助。

🌐 Our assumption was that users would read the release notes, then the migration guide, and finally install v9.0.0. Instead, many installed it, encountered an error message about a missing configuration file, and only then returned to the documentation for guidance. Many users sought help in Discord or GitHub without reading the docs first.

正如一位用户所言：“我没有额外的两个小时去阅读所有文档并弄清楚如何升级我的配置文件。请自动为我完成。”

🌐 As one user put it: “I don’t have a spare two hours to read through all the documentation and figure out how to upgrade my config file. Just do it for me automatically.”

生态系统采用速度缓慢

🌐 Ecosystem adoption was slow

尽管新配置系统的开发周期很长，并且我们直接联系了高知名度的插件和可共享配置的作者（详情请参见时间表），但生态系统的适应速度还是比预期慢。许多插件和配置作者直到 v9.0.0 处于测试版时才开始调整他们的包。

🌐 Despite the long development cycle for the new configuration system and our direct outreach to high-profile plugin and shareable config authors (see the timeline for details), the ecosystem took longer to adapt than expected. Many plugin and config authors didn’t begin adapting their packages until v9.0.0 was in beta.

有人建议推迟 v9.0.0 的发布，以给生态系统更多时间来赶上。我们出于几个原因决定不这样做：

🌐 Some suggested delaying the v9.0.0 release to give the ecosystem more time to catch up. We decided against this for several reasons:

  • 用户不需要立即升级。ESLint v8.x 仍然与整个生态系统完全兼容，并继续接收错误修复，因此那些不想升级的人可以继续使用它。
  • 目前尚不清楚这种延迟会持续多久。我们如何确定生态系统何时才算“赶上”？我们是否应将 v9.0.0 置于搁置状态，同时无限期地仅为 v8.x 提供错误修复？那似乎不是一个可行的解决方案。
  • @eslint/eslintrc 包在 v9.0.0 版本中已经为 eslintrc 插件和可共享配置提供了大量兼容性，解决了我们遇到的最常见问题。
  • 我们已经就即将到来的变更进行了18个月的沟通，并随着第一次 alpha 版本发布的临近增加了提醒。尽管采纳速度比预期慢，但我们看到势头正在建立，并希望保持这一速度。推迟发布可能会传递错误的信息，并让进一步的延迟累积扩大。

我们没有预料到对双配置插件支持的需求

🌐 We didn’t anticipate the desire for dual-config plugin support

在过程的后期逐渐清楚，许多插件和可共享配置的作者希望提供一个与旧配置系统和新配置系统都兼容的单一包。虽然事后看来这似乎很明显，但我们最初假设作者要么为 ESLint v9.0.0 发布插件的新版本并停止支持 v8.x，要么分别维护 v8.x 和 v9.x 的独立版本线。然而，许多生态系统维护者表达了对双配置支持的强烈需求。

🌐 It became clear late in the process that many plugin and shareable config authors wanted to provide a single package compatible with both the old and new configuration systems. Although this seems obvious in hindsight, we initially assumed authors would either release a new version of their plugin for ESLint v9.0.0 and stop supporting v8.x, or maintain separate release lines for v8.x and v9.x. However, many ecosystem maintainers expressed a strong desire for dual-config support.

吸取的教训

🌐 Lessons learned

根据我们在 ESLint v9.0.0 版本发布中的经验，我们总结了关键的经验教训：

🌐 From our experience with the ESLint v9.0.0 release, we’ve identified key lessons:

  • 过多的破坏性更改: 回顾过去，将配置系统的更改与规则 API 的更改打包在一起，造成了过多的中断。未来，我们将优先考虑较小且更频繁的重大版本发布，而不是较大且较少的发布。
  • 工具优先，文档其次： 用户通常没有时间仔细阅读发布说明或迁移指南。我们将更多关注工具，如代码转换工具和转换实用程序，以帮助用户快速上手。
  • **错误需要上下文：**鉴于许多用户会在阅读发行说明之前安装重大版本，我们将改进错误消息，以提供更多上下文并引导用户查阅相关文档。
  • 生态系统推广需要改进： 当重大变化即将发生时，我们需要找到更有效的方式来吸引生态系统的关注。我们以前的方法，包括博客文章、社交媒体以及通过电子邮件和拉取请求的直接接触，并不像我们预期的那样有效。

结论

🌐 Conclusion

ESLint v9.0.0 的发布是一个重要的里程碑，虽然我们为发布的许多方面感到自豪，但它也凸显了我们可以改进的字段。通过在未来的重大版本中专注于更小、更易管理的变更，优先考虑工具而非文档，并完善我们的生态系统推广，我们可以使升级过程对每个人更加顺利。从 v9.0.0 中学到的经验教训将指导我们继续发展 ESLint，并努力满足用户的需求。我们感谢社区持续的反馈，并致力于使 ESLint 成为一个更可靠、更易用的工具。

🌐 The release of ESLint v9.0.0 was a significant milestone, and while we are proud of many aspects of the rollout, it highlighted areas where we can improve. By focusing on smaller, more manageable changes in future major releases, prioritizing tooling over documentation, and refining our ecosystem outreach, we can make the upgrade process smoother for everyone. The lessons learned from v9.0.0 will guide us as we continue to evolve ESLint and work to meet the needs of our users. We appreciate the ongoing feedback from the community and are committed to making ESLint a more reliable and user-friendly tool moving forward.

Nicholas C. Zakas
ESLint Technical Steering Committee

Creator of ESLint, independent software developer, consultant, coach, and author.

来自博客

最新的 ESLint 新闻、案例研究、教程和资源。

查看所有帖子
ESLint v10.3.0 发布
Release Notes 1 min read

ESLint v10.3.0 发布

我们刚刚发布了 ESLint v10.3.0，这是 ESLint 的一次小版本升级。此版本添加了一些新功能，并修复了上一版本中发现的几个错误。

Milos Djermanovic
ESLint v10.2.1 发布
Release Notes 1 min read

ESLint v10.2.1 发布

我们刚刚发布了 ESLint v10.2.1，这是 ESLint 的一个补丁版本升级。本次发布修复了上一版本中发现的几个错误。

Francesco Trotta
ESLint v10.2.0 发布
Release Notes 2 min read

ESLint v10.2.0 发布

我们刚刚发布了 ESLint v10.2.0，这是 ESLint 的一次小版本升级。此版本添加了一些新功能，并修复了上一版本中发现的几个错误。

Francesco Trotta