Skip to main content

版本控制


我们遵循 语义版本控制 (semver)。 此页面的存在是为了帮助围绕我们认为属于每个 semver 类别的内容制定指南。

英：We follow semantic versioning (semver). This page exists to help set guidelines around what we consider to fall within each of the semver categories.

该项目中的所有包都以相同的版本号发布，以便更轻松地协调发布和安装。

英：All of the packages in this project are published with the same version number to make it easier to coordinate both releases and installations.

重大变化​

在考虑更改是否应算作 "breaking" 时，我们首先需要考虑它影响哪些包。 例如，解析器包的重大更改与 ESLint 插件的标准不同。 这是因为它们不仅具有非常不同的 API 界面，而且它们的使用方式也非常不同。

英：When considering whether a change should be counted as "breaking" we first need to consider what package(s) it impacts. For example breaking changes for the parser packages have a different standard to those for the ESLint plugins. This is because not only do they have very different API surfaces, they also are consumed in very different ways.

请注意，下面提供的列表并不详尽，旨在作为示例来帮助指导维护人员规划和审查变更。

英：Please note that the lists provided below are non-exhaustive and are intended to serve as examples to help guide maintainers when planning and reviewing changes.

ast-spec 和 visitor-keys​

如果出现以下情况，对 AST shall 的更改将被视为破坏：

英：A change to the AST shall be considered breaking if it:

  • 删除或重命名现有的 AST 节点。
  • 删除或重命名 AST 节点上的现有属性。
  • 以非精炼方式更改类型（即 string 到 number）。

如果出现以下情况，对 AST 最好不要 的更改将被视为破坏：

英：A change to the AST shall not be considered breaking if it:

  • 向 AST 添加新属性。
  • 向 AST 添加新的节点类型。
  • 将新节点类型添加到现有联合类型。
  • 将类型细化为更具体（即 string 到 'literal' | 'union'）。
  • 从联合中删除错误添加且与运行时 AST 不匹配的类型。

eslint-plugin 和 eslint-plugin-tslint​

如果需要用户更改其配置，则对插件 shall 的更改将被视为破坏。 进一步来说：

英：A change to the plugins shall be considered breaking if it will require the user to change their config. More specifically:

  • 删除或重命名选项。
  • 更改规则的默认选项。
  • 将规则的架构更改为更严格。
  • 将类型信息用于之前未使用该信息的规则。
  • 删除或重命名规则。
  • 更改任何推荐的配置。
  • 更改规则的默认行为，从而在平均代码库中的大量案例中产生新报告。

对插件 最好不要 的更改如果满足以下条件，则被视为破坏：

英：A change to the plugins shall not be considered breaking if it:

  • 添加一个选项，默认情况下不会删除现有功能。
  • 添加一条规则。
  • 弃用规则。
  • 向现有规则添加额外的检查，从而在平均代码库中的中小型案例集中生成新报告。
  • 以不引入额外报告的方式重构规则的代码。
  • 对规则的描述或其他元数据的更改。
  • 添加修复程序或建议修复程序。
  • 删除修复程序或建议修复程序。
  • 修复了规则中可能引入或不引入附加报告的不正确行为。

parser, typescript-estree, scope-manager, types, type-utils, utils​

如果出现以下情况，对这些包 shall 的更改将被视为破坏：

英：A change to these packages shall be considered breaking if it:

  • 以向后不兼容的方式更改 API 表面（删除或重命名函数、类型等）。

如果出现以下情况，对这些包 最好不要 的更改将被视为破坏：

英：A change to these packages shall not be considered breaking if it:

  • 添加到 API 表面（添加函数、类型等）。
  • 弃用部分 API 表面。
  • 将 optional 参数添加到函数或输入类型的属性。
  • 向输出类型添加附加属性。
  • 以 JSDoc 注释的形式添加文档。

内部封装​

在计算新的软件包版本时，不应考虑此项目中不属于我们公共 API 表面的任何软件包（例如 eslint-plugin-internal 或 website）。

英：Any packages in this project that are not part of our public API surface (such as eslint-plugin-internal or website) shall not be considered when calculating new package versions.