ESLint 核心规则提案指南从新规则构思到提交 PR 的完整流程【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslintESLint 以规则rules为灵魂本项目长期维护着 300 条核心规则见 lib/rules/index.js 中按字母排序的规则注册表且仍在持续演进。但并非所有规则提案都会被纳入核心因为每条核心规则必须与其余规则协同工作、保持一致的设计哲学。本文基于仓库内 propose-new-rule.md 贡献指南系统讲解「新规则如何进入 ESLint 核心」的完整链路核心规则必须满足的六项硬性标准、提案与评审的流程、被接受后的实现责任以及当提案被拒时如何通过自定义规则与插件达成同等目标。读完本文你将掌握一套可落地的规则提案与开发方法论。注意自 2020 年起ESLint 官方只接受与新 ECMAScript 特性相关的核心规则其余新规则一律建议优先以插件形式实现。这是所有提案者必须先理解的前提。核心规则指南六项硬性标准ESLint 不能随意接纳任何规则因为所有规则需要作为一个整体协调工作。整体而言ESLint 核心规则必须满足以下六项标准广泛适用Widely applicable官方分发的规则必须对大量开发者有实际价值。针对罕见模式uncommon patterns的个人偏好不被支持。这也解释了为什么仓库中的核心规则全部聚焦通用 JavaScript 语法与运行时问题。通用Generic规则不能特殊到让用户难以判断何时该启用它。一个经验法则是如果描述一条规则需要超过两个 and例如「当 a 且 b 且 c 且 d 时该规则告警」那么这条规则通常过于具体。原子性Atomic规则必须完全独立运行。核心规则被明令禁止感知其他规则的状态或存在——这正是RuleTester和 linter 都以「单条规则独立创建、独立注册」为设计单元的原因参见 lib/linter/linter.js 的规则加载机制。唯一性Unique不允许两条规则产生相同的告警。规则重叠会令最终用户困惑核心规则之间不得存在功能重叠。库无关Library agnostic规则只能基于 JavaScript 运行时环境而不能针对特定库或框架。例如核心规则不应只在「你使用 jQuery」时才适用但可以存在只在你使用 Node.js作为一种运行时时适用的规则因为 Node.js 属于运行时环境而非第三方库。无冲突No conflicts任何规则都不得与另一条规则直接冲突。例如如果存在一条要求分号的规则就不能再有一条禁止分号的规则——这正是semi一条规则同时承担「要求」与「禁止」两种模式的原因。以上是官方纳入的形式标准但每条规则最终都会在自身基础上被单独评估each rule is evaluated on its own basis。从源码结构看规则的原子性设计规则的原子性与唯一性要求可以直接在仓库实现中找到佐证。查看 lib/rules/index.js可以看到所有核心规则通过LazyLoadingRuleMap以规则名 - 懒加载工厂函数的形式注册每条规则是独立的 CommonJS 模块互不引用再看 lib/rules/no-extra-semi.js其meta中schema: []表示该规则无任何选项create(context)完全依赖context提供的 AST 遍历回调工作。这种「零外部状态、单文件自足」的结构正是原子性标准在代码层面的直接体现。如何提出一条新规则如果你想提议一条新规则请参照 pull-requests.md 中的方式创建 pull request或通过提交 issue 的方式发起讨论。仓库在 templates/rule-proposal.md 中提供了标准的新规则提案模板填写该模板所需的核心信息包括这条新规则应当做什么What should the new rule do?它与哪个新的 ECMAScript 特性相关模板明确注明我们只接受与新 ECMAScript 特性相关的新核心规则规则类别是什么——在以下两项中选择其一[ ] Warns about a potential problem对潜在问题告警[ ] Suggests an alternate way of doing something建议替代写法提供该规则将要告警的示例 JavaScript 代码模板预留了代码块供填写。为什么这条规则应被包含进 ESLint 核心而不是做成插件之所以需要所有这些信息是因为团队必须据此判断该规则是否是合格的核心规则候选determine whether or not the rule is a good core rule candidate。先寻找既有 issue 与正确标签在提交之前建议先阅读 work-on-issue.md 了解 issue 协作机制若存在相关 issue确认它是否带有accepted标签表示团队已同意接受对应 pull requestgood first issue标签适合新手issue 的类型标签rule、enhancement、feature、bug等则标明问题性质。不要为未标记为accepted的 issue 发送 pull request。新规则被接受的三项条件一条规则要被 ESLint 核心接受必须同时满足通过上文「核心规则指南」一节列出的全部标准有至少一位 ESLint 团队成员为该规则的纳入担保champion inclusion与此前 12 个月内已进入 ECMAScript Stage 4的特性相关。请记住仓库已拥有超过 200 条规则无论对最终用户还是对负责维护的 ESLint 团队而言这都是一个令人望而生畏的数量。因此任何新规则都必须被认定具有高重要性high importance才可能被纳入核心。这也是「只接受新 ECMAScript 特性相关规则」这一收口策略的动机——避免核心规则池无限膨胀。实现是你的责任ESLint 团队不会为用户建议的新规则编写实现因为团队成员数量有限需要把精力集中在整体路线图overall roadmap上。因此流程是一旦规则被接受由你负责实现并编写文档你也可以招募另一位伙伴协助实现那位担保这条规则的团队成员是你的资源负责引导你走完后续整个流程。实现落地文件结构与约定实现一条核心规则时需严格遵循 core-rules.md 中记录的三文件结构约定以规则标识符命名例如no-extra-semi文件类型位置示例源码文件lib/rules/目录lib/rules/no-extra-semi.js测试文件tests/lib/rules/目录tests/lib/rules/no-extra-semi.jsMarkdown 文档docs/src/rules/目录docs/src/rules/no-extra-semi.mdcore-rules.md同时给出规则源码的基本骨架meta含type、docs.description、fixable、schema与create(context)回调函数。仓库中 lib/rules/no-extra-semi.js 是真实范本——其meta声明type: suggestion、fixable: code、schema: []并在create(context)中通过context.sourceCode提供的getTokenAfter、getNodeByRangeIndex等 API 判断分号是否多余。每条核心规则必须同时提交对应的单元测试使用RuleTester工具且命名遵循规范禁止性规则以no-前缀如no-eval禁止eval()、no-debugger禁止debugger强制执行类规则使用无前缀的短名。规则变更走另一条通道如果你要修改的是已有核心规则增强其可配置性而非修 bug请参考同目录下的 propose-rule-change.md其接受条件为「遵守核心规则指南 有团队成员担保 该变更重要到规则没有它就不完整」。仓库在 templates/rule-change-proposal.md 中提供变更提案模板需说明变更方向产生更多告警 / 更少告警 / 实现 autofix / 实现 suggestions、实现方式新选项 / 新默认行为 / 其他以及变更前后的行为对比示例。备选方案创建你自己的规则请记住ESLint 是**完全可插拔pluggable的你可以创建自己的规则并通过插件plugins**分发。这是官方刻意为之的设计——ESLint 团队不想成为所有可能规则的守门人gatekeepers。即使一条规则未被核心接受也不代表你不能拥有自己想要的规则。详见 自定义规则文档 与 插件创建文档。从仓库结构看这条通道的证据同样充分核心规则与自定义规则共享同一套 Rule APImetacreate核心规则只是额外多承担了「包含在eslint包内」与「遵守核心规则约定」两项义务。换言之你在 lib/rules/ 中看到的每一条规则其编写方式与你本地插件中的自定义规则完全一致——唯一区别是发布位置与维护责任。提交 pull request从分支到合并当你的规则实现、测试与文档都齐备后按照 pull-requests.md 的七步流程提交在 fork 中创建描述性分支如git checkout -b issue1234一个分支只处理一个 issue修改代码与测试遵循 代码约定提交信息遵循 Conventional Commits 格式tag: 描述tag 可为fix、feat、docs、chore等正文以Fixes #1234关联 issue变基到上游git fetch upstream git rebase upstream/main运行全量测试npm test确保无回归复查提交提交信息格式正确、改动全部伴随测试、面向用户的功能全部伴随文档推送分支git push origin issue1234必要时强制推送发送 pull request并在后续跟进中监控 CI 状态、回应团队评审意见、按需补充提交或再次变基。值得强调的是该文档明确指出ESLint 项目强烈建议通过 pull request 而非「带代码片段的 issue」提交代码——后者意味着团队需要手动合并并更新测试会显著降低你的代码被及时纳入的可能性。结语核心还是插件取决于规则的性质总结这套提案方法论先对照六项核心标准自评再确认规则是否与近 12 个月内达到 Stage 4 的新 ECMAScript 特性相关然后通过模板化的 issue/PR 发起提案经团队成员担保后自行负责实现、测试与文档三件套。若未获通过插件通道始终敞开——这正是 ESLint「核心收敛、生态开放」的架构哲学核心规则池保持高质量与低重叠而长尾需求由社区插件生态承载。无论走哪条路templates/rule-proposal.md、templates/rule-change-proposal.md 与 core-rules.md 都是你起步时最值得先读的三份资料。【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ESLint 核心规则提案指南：从新规则构思到提交 PR 的完整流程
ESLint 核心规则提案指南从新规则构思到提交 PR 的完整流程【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslintESLint 以规则rules为灵魂本项目长期维护着 300 条核心规则见 lib/rules/index.js 中按字母排序的规则注册表且仍在持续演进。但并非所有规则提案都会被纳入核心因为每条核心规则必须与其余规则协同工作、保持一致的设计哲学。本文基于仓库内 propose-new-rule.md 贡献指南系统讲解「新规则如何进入 ESLint 核心」的完整链路核心规则必须满足的六项硬性标准、提案与评审的流程、被接受后的实现责任以及当提案被拒时如何通过自定义规则与插件达成同等目标。读完本文你将掌握一套可落地的规则提案与开发方法论。注意自 2020 年起ESLint 官方只接受与新 ECMAScript 特性相关的核心规则其余新规则一律建议优先以插件形式实现。这是所有提案者必须先理解的前提。核心规则指南六项硬性标准ESLint 不能随意接纳任何规则因为所有规则需要作为一个整体协调工作。整体而言ESLint 核心规则必须满足以下六项标准广泛适用Widely applicable官方分发的规则必须对大量开发者有实际价值。针对罕见模式uncommon patterns的个人偏好不被支持。这也解释了为什么仓库中的核心规则全部聚焦通用 JavaScript 语法与运行时问题。通用Generic规则不能特殊到让用户难以判断何时该启用它。一个经验法则是如果描述一条规则需要超过两个 and例如「当 a 且 b 且 c 且 d 时该规则告警」那么这条规则通常过于具体。原子性Atomic规则必须完全独立运行。核心规则被明令禁止感知其他规则的状态或存在——这正是RuleTester和 linter 都以「单条规则独立创建、独立注册」为设计单元的原因参见 lib/linter/linter.js 的规则加载机制。唯一性Unique不允许两条规则产生相同的告警。规则重叠会令最终用户困惑核心规则之间不得存在功能重叠。库无关Library agnostic规则只能基于 JavaScript 运行时环境而不能针对特定库或框架。例如核心规则不应只在「你使用 jQuery」时才适用但可以存在只在你使用 Node.js作为一种运行时时适用的规则因为 Node.js 属于运行时环境而非第三方库。无冲突No conflicts任何规则都不得与另一条规则直接冲突。例如如果存在一条要求分号的规则就不能再有一条禁止分号的规则——这正是semi一条规则同时承担「要求」与「禁止」两种模式的原因。以上是官方纳入的形式标准但每条规则最终都会在自身基础上被单独评估each rule is evaluated on its own basis。从源码结构看规则的原子性设计规则的原子性与唯一性要求可以直接在仓库实现中找到佐证。查看 lib/rules/index.js可以看到所有核心规则通过LazyLoadingRuleMap以规则名 - 懒加载工厂函数的形式注册每条规则是独立的 CommonJS 模块互不引用再看 lib/rules/no-extra-semi.js其meta中schema: []表示该规则无任何选项create(context)完全依赖context提供的 AST 遍历回调工作。这种「零外部状态、单文件自足」的结构正是原子性标准在代码层面的直接体现。如何提出一条新规则如果你想提议一条新规则请参照 pull-requests.md 中的方式创建 pull request或通过提交 issue 的方式发起讨论。仓库在 templates/rule-proposal.md 中提供了标准的新规则提案模板填写该模板所需的核心信息包括这条新规则应当做什么What should the new rule do?它与哪个新的 ECMAScript 特性相关模板明确注明我们只接受与新 ECMAScript 特性相关的新核心规则规则类别是什么——在以下两项中选择其一[ ] Warns about a potential problem对潜在问题告警[ ] Suggests an alternate way of doing something建议替代写法提供该规则将要告警的示例 JavaScript 代码模板预留了代码块供填写。为什么这条规则应被包含进 ESLint 核心而不是做成插件之所以需要所有这些信息是因为团队必须据此判断该规则是否是合格的核心规则候选determine whether or not the rule is a good core rule candidate。先寻找既有 issue 与正确标签在提交之前建议先阅读 work-on-issue.md 了解 issue 协作机制若存在相关 issue确认它是否带有accepted标签表示团队已同意接受对应 pull requestgood first issue标签适合新手issue 的类型标签rule、enhancement、feature、bug等则标明问题性质。不要为未标记为accepted的 issue 发送 pull request。新规则被接受的三项条件一条规则要被 ESLint 核心接受必须同时满足通过上文「核心规则指南」一节列出的全部标准有至少一位 ESLint 团队成员为该规则的纳入担保champion inclusion与此前 12 个月内已进入 ECMAScript Stage 4的特性相关。请记住仓库已拥有超过 200 条规则无论对最终用户还是对负责维护的 ESLint 团队而言这都是一个令人望而生畏的数量。因此任何新规则都必须被认定具有高重要性high importance才可能被纳入核心。这也是「只接受新 ECMAScript 特性相关规则」这一收口策略的动机——避免核心规则池无限膨胀。实现是你的责任ESLint 团队不会为用户建议的新规则编写实现因为团队成员数量有限需要把精力集中在整体路线图overall roadmap上。因此流程是一旦规则被接受由你负责实现并编写文档你也可以招募另一位伙伴协助实现那位担保这条规则的团队成员是你的资源负责引导你走完后续整个流程。实现落地文件结构与约定实现一条核心规则时需严格遵循 core-rules.md 中记录的三文件结构约定以规则标识符命名例如no-extra-semi文件类型位置示例源码文件lib/rules/目录lib/rules/no-extra-semi.js测试文件tests/lib/rules/目录tests/lib/rules/no-extra-semi.jsMarkdown 文档docs/src/rules/目录docs/src/rules/no-extra-semi.mdcore-rules.md同时给出规则源码的基本骨架meta含type、docs.description、fixable、schema与create(context)回调函数。仓库中 lib/rules/no-extra-semi.js 是真实范本——其meta声明type: suggestion、fixable: code、schema: []并在create(context)中通过context.sourceCode提供的getTokenAfter、getNodeByRangeIndex等 API 判断分号是否多余。每条核心规则必须同时提交对应的单元测试使用RuleTester工具且命名遵循规范禁止性规则以no-前缀如no-eval禁止eval()、no-debugger禁止debugger强制执行类规则使用无前缀的短名。规则变更走另一条通道如果你要修改的是已有核心规则增强其可配置性而非修 bug请参考同目录下的 propose-rule-change.md其接受条件为「遵守核心规则指南 有团队成员担保 该变更重要到规则没有它就不完整」。仓库在 templates/rule-change-proposal.md 中提供变更提案模板需说明变更方向产生更多告警 / 更少告警 / 实现 autofix / 实现 suggestions、实现方式新选项 / 新默认行为 / 其他以及变更前后的行为对比示例。备选方案创建你自己的规则请记住ESLint 是**完全可插拔pluggable的你可以创建自己的规则并通过插件plugins**分发。这是官方刻意为之的设计——ESLint 团队不想成为所有可能规则的守门人gatekeepers。即使一条规则未被核心接受也不代表你不能拥有自己想要的规则。详见 自定义规则文档 与 插件创建文档。从仓库结构看这条通道的证据同样充分核心规则与自定义规则共享同一套 Rule APImetacreate核心规则只是额外多承担了「包含在eslint包内」与「遵守核心规则约定」两项义务。换言之你在 lib/rules/ 中看到的每一条规则其编写方式与你本地插件中的自定义规则完全一致——唯一区别是发布位置与维护责任。提交 pull request从分支到合并当你的规则实现、测试与文档都齐备后按照 pull-requests.md 的七步流程提交在 fork 中创建描述性分支如git checkout -b issue1234一个分支只处理一个 issue修改代码与测试遵循 代码约定提交信息遵循 Conventional Commits 格式tag: 描述tag 可为fix、feat、docs、chore等正文以Fixes #1234关联 issue变基到上游git fetch upstream git rebase upstream/main运行全量测试npm test确保无回归复查提交提交信息格式正确、改动全部伴随测试、面向用户的功能全部伴随文档推送分支git push origin issue1234必要时强制推送发送 pull request并在后续跟进中监控 CI 状态、回应团队评审意见、按需补充提交或再次变基。值得强调的是该文档明确指出ESLint 项目强烈建议通过 pull request 而非「带代码片段的 issue」提交代码——后者意味着团队需要手动合并并更新测试会显著降低你的代码被及时纳入的可能性。结语核心还是插件取决于规则的性质总结这套提案方法论先对照六项核心标准自评再确认规则是否与近 12 个月内达到 Stage 4 的新 ECMAScript 特性相关然后通过模板化的 issue/PR 发起提案经团队成员担保后自行负责实现、测试与文档三件套。若未获通过插件通道始终敞开——这正是 ESLint「核心收敛、生态开放」的架构哲学核心规则池保持高质量与低重叠而长尾需求由社区插件生态承载。无论走哪条路templates/rule-proposal.md、templates/rule-change-proposal.md 与 core-rules.md 都是你起步时最值得先读的三份资料。【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考