乐趣区

关于开源:如何贡献复杂的项目

jiezi

​Iteration 121 从 4/23 开始到 5/6 完结，为期两周。这个周期胜利走出了本人的舒服圈，摸索了不少之前本人从未理解的货色，比方 tree-sitter，parser，hdfs，java 等等，感觉播种十分多。最近重复读了很多遍 @mitchellh2 写的 Contributing to Complex Projects3，明天这份周报就联合本人从零开始参加奉献 difftastic4 的经验来介绍如何奉献简单的我的项目。

前言

Contributing to Complex Projects 文章中将奉献简单我的项目合成为如下几步：

  • Step 1: Become a User，成为用户
  • Step 2: Build the Project，构建我的项目
  • Step 3: Learn the Hot-Path Internals，学习外部的要害逻辑
  • Step 4: Read and Reimplement Recent Commits，浏览并从新实现最近的 commits
  • Step 5: Make a Bite-sized Change，做一个小变更

这些步骤实用于绝大多数我的项目，不过须要依据集体的偏好和理论状况做一些调整。比方我更偏向于做一些能最终合并到骨干的事件，所以我参加奉献的过程中往往会略过这里的 Step 4 并间接尝试实现一些绝对容易的 feature。大家在参加奉献的过程也须要视状况调整本人的策略，不要教条式地照搬这里的步骤。

对于 difftastic

difftastic5 是一个应用 Rust 开发的能了解语义的 diff 工具。

它可能了解咱们在代码中批改的字符是数组的 Item 还是函数的参数，以 Javascripts 为例：

• 高亮了 {,} 然而这里的 foo(); 并没有批改，只管 indent 变了，因为它了解嵌套
• 将右边的 bar() 和左边的 bar(1) 对齐，因为它晓得他们是同一个 function call。
• 这里的 eric 被挪动到了下一行，然而并没有被高亮进去，因为它晓得这是一个不扭转语义的换行。

在背地，difftastic 应用 tree-sitter^6 来解析并比照文件的 AST，而不是基于纯字符的差别比照。

目前 difftastic 反对 30 多种编程语言和配置文件的 diff，并可能运行在 Linux，MacOS，Windows 等支流平台上。

成为用户

开源我的项目十分乏味的一点就在于：开发者往往是用户自身。Arch 之道中的 User centrality 准则指出：

许多 Linux 发行版都试图变得更“用户敌对”，Arch Linux 则始终是，永远会是“以用户为核心”。此发行版是为了满足贡献者的需要，而不是为了吸引尽可能多的用户。Arch 实用于乐于本人入手的用户，他们违心花工夫浏览文档，解决本人的问题。

我认为这才是参加开源最重要的一步。成为用户，去应用它，去了解它是做什么的，去被动发现有余和改良点，而不是一上来就抱着长长的设计文档啃。很多同学的开源激情往往就消磨在漫长的文档浏览过程中：咱们并不需要成为这个方面的专家能力参加我的项目的奉献。在奉献 difftastic 之前，我对 parser，tree-sitter 无所不知。即便是当初，我也对他们的理解也只局限于他们是做什么的，并不知道他们到底如何工作，更别提浏览他们的代码了。然而这并不障碍我为 difftastic 奉献了多种语言的反对，并修复若干个引起 Crash 的 BUG。绝大多数开源我的项目都会提供装置和应用的文档，difftastic 也不例外。我参考 Installation7 和 Usage8 中胜利装置并配置好了 difftastic。我很快发现 difftastic 短少对 perl 和 hcl 的反对，于是决定为它加上。

构建我的项目

参加开源我的项目的第二步是部署开发环境并进行胜利的构建。difftastic 是一个纯 Rust 的我的项目，相干的依赖比拟少，应用 cargo build 即可编译。

而简单的我的项目往往会有着简单的依赖，有些是我的项目必须的依赖，包含语言的构建工具，依赖治理，编译时工具等等，有些是我的项目开发过程中须要用到的工具，比方动态查看，代码格式化，集成测试等等。保护品质比拟好的我的项目往往会提供 Contributing 或者 Get Started 文档来告知咱们如何构建我的项目，比方 TiDB 在 TiDB Development Guide: Get Started9 中具体介绍了编译 TiDB 须要依赖和步骤。更进一步的，有的我的项目会提供一个一键式脚本（只管我并不喜爱这种）来解决依赖问题，比方 Databend 提供了 dev_setup.sh10。像 Rust11 这样开发环境配置高度简单的我的项目还会开发额定的工具 12 来自动化这些步骤。

作为开发者，咱们须要做到的事件是残缺的浏览 README 并寻找相似的信息。如果没找到的话能够尝试约定俗成的形式，比方我的项目下有 Makefile，package.json，Cargo.toml，go.mod 这些标志性的文件，咱们能够间接尝试应用对应的命令。在胜利构建后，咱们能够尝试为我的项目提交一个批改 README 并减少构建步骤的文档以不便起初的同学。

学习要害门路

参加开源我的项目的第三步是学习要害门路。@mitchellh 将本人的办法概括为：trace down, learn up.：当学习某个个性时：

  • 首先自顶向下的寻找波及到这个个性的 codepath 并疏忽与之无关的细节
  • 而后自底向上的学习这个子系统是如何工作的
  • 尝试去批改代码，减少新的 log，减少简略的逻辑，批改某处细节，去了解为什么不工作了
  • 浏览与这个个性无关的文档或者分享

不难发现，咱们日常的学习和工作中往往也是如此，只是咱们须要零碎的使用到开源我的项目中。我的项目中的代码散布往往也遵循二八定律：20% 的代码实现了 80% 的性能，所以咱们没有必要尝试了解我的项目中每一行代码的细节。最好的形式是带着问题来浏览代码，只寻找跟本人实现性能无关的逻辑。保护良好的开源我的项目往往会为外围的逻辑和模块增加粗疏的文档来解决常见的疑难，很多时候看文档就能解决咱们的问题。

difftastic 就是如此，作者十分棒地提供了 Adding A Parser13 的文档。在文档的帮忙下，我只须要依照步骤顺次执行并解决简略的编译问题即可。当然，更多的时候咱们会面临文档的缺失和有余，这时候咱们在了解这一模块后为我的项目奉献这份文档。就算了解谬误也没有关系，在提交 PR 时咱们能够跟作者进行探讨和确认，一方面可能帮忙到有雷同问题的贡献者，另一方面也能加深本人的了解和意识。

从小变更做起

参加开源的第四步是从小变更做起。奉献文档就是很好的开始，这可能帮忙咱们了解这个我的项目是如何进行探讨和开发的。

请尽量避免上来就承当特地简单的工作，一方面咱们须要通过奉献来积攒本人在社区的名誉，另一方面简单工作中途夭折会极大地打击本人的信念。比拟举荐的形式是从比拟小的性能做起，最好可能把影响局限在以后的子系统。随同着咱们实现性能，咱们就可能从以后模块登程，去了解更多的模块如何独特工作。随着理解的模块增多，咱们可能发现更多能够改良的点，参加到我的项目的继续演进中去。

在 fix: Remove trailing lines before calculating max_lines14 中，我通过减少一些简略的 println 发现了问题的本源在 LineNumber 计算有误，从而给出了一个 fix：

- (max(1, self.as_ref().split('\n').count()) - 1).into()
+ (max(1, self.as_ref().trim_end().split('\n').count()) - 1).into()

然而很快我发现这行代码有些难以了解，所以我进行了简略的重构：

-        (max(1, self.as_ref().trim_end().split('\n').count()) - 1).into()
+        self.as_ref()
+            .trim_end() // Remove extra trailing whitespaces.
+            .split('\n') // Split by `\n` to calculate lines.
+            .count()
+            .sub(1) // Sub 1 to make zero-indexed LineNumber
+            .into()

上述的变更都没有批改到别的模块，因而我只须要减少一个独立的单元测试即可，而作者可能疾速的验证我的思路是否正确，防止了在 PR 中进行来回的探讨拉锯。

总结

奉献简单的开源我的项目并不艰难，把握正确的方法论，咱们都可能退出到开源的行列中来：

  • 成为用户
  • 构建我的项目
  • 学习要害门路
  • 从小变更做起

欢送退出开源社区～

对于 Databend

Databend 是一款开源、弹性、低成本，基于对象存储也能够做实时剖析的旧式数仓。期待您的关注，一起摸索云原生数仓解决方案，打造新一代开源 Data Cloud。

  • Databend 文档：https://databend.rs/
  • Twitter：https://twitter.com/Datafuse_…
  • Slack：https://datafusecloud.slack.com/
  • Wechat：Databend
  • GitHub：https://github.com/datafusela…


文章首发于公众号：Databend

  1. https://github.com/users/Xuan… ↩
  2. https://github.com/mitchellh ↩
  3. https://mitchellh.com/writing… ↩
  4. https://github.com/Wilfred/di… ↩
  5. https://github.com/Wilfred/di… ↩
  6. *https://tree-sitter.github.io… ↩
  7. https://difftastic.wilfred.me… ↩
  8. https://difftastic.wilfred.me… ↩
  9. https://pingcap.github.io/tid… ↩
  10. https://github.com/datafusela… ↩
  11. https://github.com/rust-lang/… ↩
  12. https://github.com/rust-lang/… ↩
  13. https://difftastic.wilfred.me… ↩
  14. https://github.com/Wilfred/di…* ↩
退出移动版