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 Changes

在考虑是否应将更改计入 "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-spec and visitor-keys

如果发生以下情况，对 AST 的更改将被视为破坏性更改：

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

  • 删除或重命名现有的 AST 节点。

    ¥Removes or renames an existing AST Node.

  • 删除或重命名 AST 节点上的现有属性。

    ¥Removes or renames an existing property on an AST Node.

  • 以非细化方式更改类型（即 string 到 number）。

    ¥Changes a type in a non-refining way (i.e. string to number).

如果发生以下情况，对 AST 的更改将不被视为破坏性更改：

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

  • 向 AST 添加新属性。

    ¥Adds a new property to the AST.

  • 向 AST 添加新的节点类型。

    ¥Adds a new node type to the AST.

  • 将新节点类型添加到现有联合类型。

    ¥Adds a new node type to an existing union type.

  • 将类型细化为更具体（即 string 到 'literal' | 'union'）。

    ¥Refines a type to be more specific (i.e. string to 'literal' | 'union').

  • 从联合中删除错误添加且与运行时 AST 不匹配的类型。

    ¥Removes a type from a union that was erroneously added and did not match the runtime AST.

eslint-plugin​

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

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

  • 删除或重命名选项。

    ¥Removes or renames an option.

  • 更改规则的默认选项。

    ¥Changes the default option of a rule.

  • 将规则的架构更改为更严格。

    ¥Changes a rule's schema to be stricter.

  • 将类型信息用于之前未使用该信息的规则。

    ¥Consumes type information to a rule that did not previously consume it.

  • 删除或重命名规则。

    ¥Removes or renames a rule.

  • 更改任何推荐的配置。

    ¥Changes any of the recommended configurations.

  • 更改规则的默认行为，从而在平均代码库中的大量案例中产生新报告。

    ¥Changes the default behavior of a rule in such a way that causes new reports in a large set of cases in an average codebase.

如果发生以下情况，对插件的更改将不被视为破坏性更改：

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

  • 添加一个选项，默认情况下不会删除现有功能。

    ¥Adds an option that by default does not remove existing functionality.

  • 添加一条规则。

    ¥Adds a rule.

  • 弃用规则。

    ¥Deprecates a rule.

  • 向现有规则添加额外的检查，从而在平均代码库中的中小型案例集中生成新报告。

    ¥Adds additional checks to an existing rule that causes new reports in a small-to-medium set of cases in an average codebase.

  • 以不引入额外报告的方式重构规则的代码。

    ¥Refactors a rule's code in a way that does not introduce additional reports.

  • 对规则的描述或其他元数据的更改。

    ¥Changes to a rule's description or other metadata.

  • 添加修复程序或建议修复程序。

    ¥Adds a fixer or suggestion fixer.

  • 删除修复程序或建议修复程序。

    ¥Removes a fixer or suggestion fixer.

  • 修复规则中可能引入或不引入额外报告的不正确行为。

    ¥Fixes incorrect behavior in a rule that may or may not introduce additional reports.

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

如果发生以下情况，对这些包的更改将被视为破坏性更改：

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

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

    ¥Changes the API surface in a backwards-incompatible way (remove or rename functions, types, etc).

如果发生以下情况，对这些包的更改将不被视为破坏性更改：

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

  • 添加到 API 表面（添加函数、类型等）。

    ¥Adds to the API surface (add functions, types, etc).

  • 弃用部分 API 表面。

    ¥Deprecates parts of the API surface.

  • 向函数添加可选参数或向输入类型添加属性。

    ¥Adds optional arguments to functions or properties to input types.

  • 向输出类型添加附加属性。

    ¥Adds additional properties to output types.

  • 以 JSDoc 注释的形式添加文档。

    ¥Adds documentation in the form of JSDoc comments.

内部封装​

¥Internal packages

在计算新包版本时，不应考虑此项目中不属于我们公共 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.