提交 Pull Request
如果您想为 ESLint 仓库做贡献,请使用 GitHub Pull Request。这是我们评估您的代码并将其合并到代码库中的最快方式。请不要在问题中提交代码片段。这样做意味着我们需要手动合并更改并更新任何相关的测试。这会降低您的代码及时纳入的可能性。请使用 Pull Request。
入门
如果您想处理 Pull Request 并且之前从未提交过代码,请按照以下步骤操作
- 设置一个开发环境。
- 如果您要实施重大更改或对核心进行更改,请确保有一个问题描述了您正在做的事情,并且该问题已被接受。您可以创建一个新问题,或者只是表明您正在处理现有问题。错误修复、文档更改和其他 Pull Request 不需要问题。
之后,您就可以开始处理代码了。
使用代码
提交 Pull Request 的过程非常简单,通常每次都遵循相同的模式
有关每个步骤的详细信息如下所示。
步骤 1:创建一个新分支
发送 Pull Request 的第一步是在您的 ESLint fork 中创建一个新分支。为分支指定一个描述性的名称,说明您要修复的内容,例如
git checkout -b issue1234
您应该在此分支中完成此问题的全部开发工作。
注意:不要将多个问题的修复合并到一个分支中。为每个要处理的问题使用单独的分支。
步骤 2:进行更改
对代码和测试进行更改,并在过程中遵循代码约定。完成后,将更改提交到您的分支
git add -A
git commit
所有 ESLint 项目都遵循Conventional Commits 作为我们的提交消息。(注意:我们不支持消息中的可选范围。)以下是一个提交消息示例
tag: Short description of what you did
Longer description here if necessary
Fixes #1234
提交消息的第一行(摘要)必须具有特定的格式。此格式由我们的构建工具检查。虽然提交消息本身没有直接检查,但它将用于生成 Pull Request 的标题,并在提交 Pull Request 时检查。
tag
是以下之一
fix
- 用于错误修复。feat
- 用于向后兼容的增强功能或添加报告问题的规则更改。fix!
- 用于向后不兼容的错误修复。feat!
- 用于向后不兼容的增强功能或特性。docs
- 仅更改文档。chore
- 用于对用户不可见的更改。build
- 仅更改构建过程。refactor
- 不影响 API 或用户体验的更改。test
- 仅更改测试文件。ci
- 更改我们的 CI 配置文件和脚本。perf
- 提高性能的代码更改。
使用您正在处理的问题的标签来确定最佳标签。
消息摘要应为更改的单句描述,并且长度必须为 72 个字符或更短。如果 Pull Request 解决了某个问题,则应在提交消息正文中以 Fixes #1234
的格式提及问题编号。如果提交没有完全解决问题,则使用 Refs #1234
而不是 Fixes #1234
。
以下是一些良好的提交消息摘要示例
build: Update Travis to only test Node 0.10
fix: Semi rule incorrectly flagging extra semicolon
chore: Upgrade Esprima to 1.2, switch to using comment attachment
步骤 3:重新设定基础到上游
在发送 Pull Request 之前,请确保重新设定基础到上游源。这可确保您的代码在最新的可用代码上运行。
git fetch upstream
git rebase upstream/main
步骤 4:运行测试
重新设定基础后,请务必再次运行所有测试,以确保没有任何错误。
npm test
如果存在任何失败的测试,请更新您的代码,直到所有测试都通过。
步骤 5:仔细检查您的提交
您的代码准备就绪后,现在是仔细检查您的提交的好时机,以确保它遵循我们的约定。以下是需要检查的事项
- 提交消息格式正确。
- 更改不会引入功能性回归。请务必运行
npm test
以在提交 Pull Request 之前验证您的更改。 - 为不相关的更改创建单独的 Pull Request。包含多个不相关更改的大型 Pull Request 可能会在未合并的情况下关闭。
- 所有更改都必须附带测试,即使您正在处理的功能之前没有测试。
- 所有用户界面更改都必须附带相应的文档。
- 遵循代码约定。
步骤 6:推送您的更改
接下来,将您的更改推送到您的克隆
git push origin issue1234
如果您由于某些引用过旧而无法推送,请改用强制推送
git push -f origin issue1234
步骤 7:发送 Pull Request
现在您已准备好发送 Pull Request。转到您的 ESLint fork,然后按照GitHub 文档 中关于如何发送 Pull Request 的说明操作。
为了向 ESLint 项目提交代码或文档,您在发送第一个 Pull Request 时将被要求签署我们的 CLA。(在https://cla.openjsf.org/ 上阅读有关 OpenJS Foundation CLA 流程的更多信息。)
Pull Request 标题是从第一个提交的摘要自动生成的,但在提交 Pull Request 之前可以进行编辑。
Pull Request 的描述应解释您所做的操作以及其效果如何体现。
合并 Pull Request 后,其提交将被压缩成一个单一的提交。压缩提交消息的第一行将包含 Pull Request 的标题和 Pull Request 编号。Pull Request 标题格式很重要,因为这些标题用于为每个版本创建变更日志。标签和问题编号有助于创建更一致和有用的变更日志。
跟进
发送 Pull Request 后,团队将对其进行审查。因此,请确保
- 监视 Pull Request 的 GitHub Actions CI 构建状态。如果失败,请调查原因。我们不会出于任何原因合并导致 CI 构建失败的 Pull Request。
- 回复团队成员在 Pull Request 上留下的评论。请记住,我们希望帮助您提交代码,因此请积极接受我们的反馈。
- 我们可能会要求您进行更改、重新设定基础或压缩提交。
更新 Pull Request 标题
如果您的 Pull Request 标题格式不正确,我们将要求您更新它。您可以通过 GitHub 用户界面执行此操作。
更新代码
如果我们要求您更改代码,则无需关闭 Pull Request 并创建一个新的。只需返回到 fork 中的分支并进行更改。然后,准备好后,您可以将更改添加到分支中
git add -A
git commit
git push origin issue1234
更新代码时,通常最好将其他提交添加到您的分支,而不是修改原始提交,因为审阅者可以轻松地分辨出哪些更改是在响应特定审阅时做出的。当我们合并 Pull Request 时,我们将压缩您分支中的所有提交,并在 main
分支上创建一个单一的提交。
后续提交中的提交消息不需要任何特定格式,因为这些提交不会显示在变更日志中。
重新设定基础
如果您的代码已过时,我们可能会要求您重新设定基础。这意味着我们希望您在最新的上游代码之上应用您的更改。请确保您已设置了开发环境,然后您可以使用以下命令重新设定基础
git fetch upstream
git rebase upstream/main
您可能会发现在尝试重新设定基础时出现合并冲突。请解决冲突,然后对您的分支进行强制推送
git push origin issue1234 -f