此页面内容来自 JSHint 项目仓库。如果您发现错误，请 提交问题 或（更佳）提交 Pull Request！

如何贡献

对项目的贡献通常采取以下三种形式之一

  • 错误报告
  • 功能请求
  • 补丁

本文档描述了为每种贡献提供最佳方式。维护团队将分配以下标签之一来记录报告的严重性

  • P1: 某些内容引发异常；破坏了 JSHint 的向后兼容性。
  • P2: 某些内容未被正确解析。
  • P3: 核心团队将在完成 P2 和 P1 后处理的功能。
  • P4: 欢迎提供补丁；请求很好，但优先级较低。

错误报告

如果您认为已识别出不正确的行为，请通过提交问题告知团队。为了帮助团队诊断和解决问题，问题报告应包含以下信息

  • 正在使用的 JSHint 版本
  • 输入源代码（简化为仅包含演示问题所需的详细信息）
  • 配置值
  • 预期行为的描述
  • 实际行为的描述

请避免使用屏幕截图来演示问题。用纯文本描述您的问题（并在适当的地方使用“代码”Markdown 格式）将使您的报告更容易被更多人访问，并更容易通过搜索引擎找到。

功能请求

如果您认为某些新功能可以改进 JSHint，我们很乐意听到您的想法！优秀的特性请求包含以下信息

  • 该特性解决的问题的描述
  • 该特性的预期操作概述
  • 任何边缘情况/异常情况的列表，以及如何处理它们

如果您能够实现该功能并提交补丁，那就更好了！请首先提交功能请求，以便维护人员验证其是否合适并帮助确定其设计。

补丁

确保解决您的问题的最佳方法是提交补丁。我们通过所有媒介接受补丁：Pull Request、电子邮件、问题评论、带有代码片段链接的推文等。

但是，在发送补丁之前，请确保以下内容适用

  • 您的提交消息遵循 提交消息指南。
  • 您的补丁没有无用的合并提交。
  • 您的编码风格与我们的相似（见下文）。
  • 您的补丁已 100% 测试。我们不接受任何测试回归。
  • 所有测试和 lint 检查都已通过（npm test）。
  • 您了解我们非常感谢您的补丁。

开发环境

JSHint 使用 Node.js 开发，并且在其 package.json 文件中指定了许多依赖项。要安装它们，只需在您的仓库目录中运行以下命令即可

$ npm install

之后，您将能够使用 bin/jshint 运行 JSHint 的边缘版本，或使用 bin/build 构建发布包。

编码风格

本节描述了我们的编码风格指南。您可能不同意它，这很好，但如果您要向我们发送补丁，请将本指南视为法律。

我们的主要规则很简单

任何代码库中的所有代码都应该看起来像是一个人输入的，无论有多少人参与贡献。 —idiomatic.js

空格

  • 我们在任何地方都使用两个空格。
  • 在 if、for、while 等之后使用一个空格。

  • 匿名函数的 function 和 ( 之间没有空格，命名函数的名称和 ( 之间没有空格

    var a = function() {};
function a() {}

  • 如果可以使代码看起来更好，可以随意缩进变量赋值或属性定义。但不要滥用它

    // Good
var next = token.peak();
var prev = token.peak(-1);
var cur  = token.current;

var scope = {
  name:   "(global)",
  parent: parentScope,
  vars:   [],
  uses:   []
};

// Bad
var cur         = token.current;
var isSemicolon = cur.isPunctuator(";");

  • 将多行注释的两侧都用换行符包装。

变量

  • 每个变量使用一个 var，除非您不为其分配任何值（并且它足够短）。

    var token = tokens.find(index);
var scope = scopes.current;
var next, prev, cur;

  • 不要对变量名进行过度描述，但也不要滥用单字母变量。在两者之间找到一个合适的点。

注释

  • 注释所有不明显的内容。
  • 如果您添加了新的检查，请编写注释描述此检查的重要性以及它检查的内容。

其他

  • 始终使用严格模式。
  • 始终使用严格比较：=== 和 !==。
  • 使用分号。
  • 不要使用逗号优先表示法。
  • 除非它确实有帮助（例如在测试中），否则请勿链接内容。

  • 如果您未分配结果，请勿短路表达式。

    // Good
token = token || tokens.find(0);

// Bad
token.isPunctuator(";") && report.addWarning("W001");

// Good
if (token.isPunctuator(";"))
  report.addWarning("W001");

提交消息指南

提交消息采用简单的格式编写，清楚地描述了更改的目的。

总体格式应如下所示

[[TYPE]] <Short description>
<Blank line>

<Body / Detailed description>

<Footer>

提交消息中的行长度没有严格限制，但良好的提交消息的标题不应超过 60 个字符，主体/页脚应在 100 列处换行。这在 Github 的 UI 上呈现效果很好。

标题

第一行是提交消息标题，它将指示更改的类型以及更改的总体描述。理想情况下，这应该在 60 个字符内。例如

[[FIX]] Ignore "nocomma" when parsing object literals

标题 [[FIX]] 表示更改是错误修复，而其余部分则阐明更改实际包含的内容。

JSHint 使用多种提交类型

  1. [[FIX]] --- 提交修复了错误或回归
  2. [[FEAT]] --- 提交引入了新功能
  3. [[DOCS]] --- 提交修改了文档。文档提交仅应修改源代码中的注释，或用于生成文档的脚本和资产。
  4. [[TEST]] --- 提交仅修改测试或测试基础设施
  5. [[CHORE]] --- 提交影响 dev-ops、CI 或包依赖项

主体

<Body> 是详细的提交消息，解释了确切更改的内容以及原因摘要。主体中的行应换行到 100 个字符，以获得最佳呈现效果。

有关历史示例，请参阅此 示例

页脚

<Footer> 包含任何重大更改的描述，无论多么细微，以及此提交影响或修复的问题列表。页脚中的行应换行到 100 个字符，以获得最佳呈现效果。

例如

[[FEAT]] Enable `norecurs` option by default

Commit 124124a7f introduced an option which forbids recursion. We liked it so much, we've enabled
it by default.

BREAKING CHANGE:

This change will break the CI builds of many applications and frameworks.

In order to work around this issue, you will need to re-engineer your applications and frameworks
to avoid making recursive calls. Use Arrays as stacks rather than relying on the VM call stack.

Fixes #1000009
Closes #888888
Closes #77777