Get started #

仔细阅读项目自述文件（README），遵循贡献指南（CONTRIBUTION）中给出的流程。

面对一个新的项目，尤其是在相对不熟悉的领域，有如下的方法可以帮助你提供前期的贡献：

• 文档贡献，这是非常有效的一种了解项目的方式，通常我们可以在阅读文档的过程中，修复一些错别字、标点符号、语法错误、无效链接等等
• good-first-issue，对于希望收到更多贡献的项目而言，会在一些容易上手的 issues 上添加该标签

Issues #

常见误区：

• 只有标题，没有内容
• 只有结果、现象，没有提供上下文
  • 问题出现的可能性千千万，没有人能猜到你的环境、操作步骤
• 只有截图，不提供错误、异常、上下文的关键文字
  • 没有文字的话，不便于其他人进行检索

最佳实践：

• 现有的 issues 中没有提到过该问题时再提交新的
• 熟悉语言一定要遵循对应社区期望的规定
• 标题要简洁、规范
• 做好分类，可以通过标签或者标题前缀来分类
  • 常见的标题分类法：Question: xxx, Proposal: xxx, Bug: xxx
• 和 UI 相关的 issues 要给出截图

Pull Request #

常见误区：

• 使用单一分支（例如：master）提交变更
• 单个 PR 中包含多个不同的优化、缺陷修复
• 单个 PR 不断新增内容
• 合并自己提交的 PR
• 通过及时聊天工具催促特定的人 review 你的 PR

最佳实践：

• 首次提交 PR 前，浏览已经成功合并过的 PR 评论列表以及格式等
• 如果要修复的问题已经有对应的 issue，请确保没有人提交对应的 PR，然后，请留言说明你的修复计划
• 如果估计你提交的变更比较多，请首先创建 issue，并依据具体情况（难易程度、争议性等）描述你的想法
• 一个 PR 只能包含一类修改
• 对于 feature 或者 bugfix 相对复杂的情况，也要考虑到如何能给 reviewer 减轻 review 压力
  • 首先，思考下是否可以把一个“大型” PR 分成多个
  • 在提交 PR 之前，确保已经进行了充分的自测，并一定要关注下你的 commit 记录（相当于“卷面分”），只保留你希望被合并到上游的记录（其他的都可以提前 squash）
  • 小技巧：可以先在自己的 fork 后的仓库中提交一个 PR 来复查下，看看是否足够“优雅”
• 每次提交都需要新增一个分支进行
• 避免同一个主题的 PR 反复关闭、新建
  • 避免在同一个 PR 中频繁地提交，这对于 reviewers 来说将会是极大的困扰
  • 如果你的 PR 还没有准备好接受 review，请在标题上添加前缀 WIP: ，直到你自测充分
  • 在根据 reviewers 提出的建议进行修改时，避免使用强制推送 --force，这对于 reviewers 来说将无法轻松地看到你最新修改的部分
  • 尽可能保持你的 commit 记录比较优雅，万一多次 review 后的记录比较多的话，项目 owners 会在合并时决定是否会 squash 你的提交记录
• 尽可能多地给出当前 PR 的详情，包括但不限于：相关 issues、解决的问题、任何方便 review 的上下文
  • 涉及到 UI 的改动，给出修改前后的效果截图
  • 视情况给出你的自测过程
  • 对于可能引起争议的部分，给出你的解释
• 如果你的 PR 超过一周没有得到 review，可以尝试 cc 相关的 team
  • 如果没有相关的 team 可以 cc 的话，可以找最近合并过类似 PR 的人，并说明是由于找不到其他的方式，以及表示抱歉打扰

以下是常见的流程：