Skip to content

Latest commit

 

History

History
55 lines (49 loc) · 3.69 KB

how-to-contribute.md

File metadata and controls

55 lines (49 loc) · 3.69 KB

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 的人,并说明是由于找不到其他的方式,以及表示抱歉打扰

以下是常见的流程: image