改进 GitHub 工作流的 15 个建议

0.524字数 2846阅读 1463

简评:GABO ESQUIVEL 拥有 10 年以上的软件开发经验,在这篇文章中,他分享了他认为最为高效和实用的开发流程,这个流程可以被用在各种软件开发项目上,开发出高质量的软件。

关于作者

高质量的软件有很多属性,比如健壮性、模块化、安全性、高性能等。本文主要关注以下几点:

  • 良好的文档:README、文档页面、变更日志
  • 良好的编码规范
  • 版本管理
  • 自动化测试:不需要太多,专注在功能性非回归测试就可以了
  • 开发者体验

为了达成上述目标,我建议使用开源工具来协助和自动化大部分任务。Git 和 GitHub 已经彻底改变了开源项目的开发方式,Git 成为版本管理事实上的标准,而 GitHub 成为代码协作的主要平台。

GitHub 官方建议的开发流程叫作 Github Flow,官网上有详细的文档 https://guides.github.com/introduction/flow。大部分开源项目都遵循这一流程,然后加入一些细微的调整。

GitHub 工作流非常灵活,它没有规定如何发布版本和记录变更,没有规定如何合并 PR,没有规定使用哪一种工具,没有规定代码提交标准,没有规定如何进行代码评审,一切都取决于开发者自己。

不同的团队有不同的需求,所以并不存在标准的解决方案。

以下是根据我的经验总结出来的清单。我主要专注于 JavaScript 开发,所以我提到的很多工具都是 JS 生态系统的一部分,不过同样的原则也适用于其他编程语言。

1. 通过 GitHub 的项目功能给问题安排优先级和跟踪进度

2016 年 9 月,GitHub 引入了项目功能,让开发者可以创建看板风格的面板,用于管理、组织和跟踪工作内容。如果你在使用 GitHub,我强烈建议使用这一个功能。更多的细节可以参看 Tracking the progress of your work with project boards.

2. 使用标签给问题分类

GitHub 提供了非常好用的过滤功能。如果你在开发开源项目,一定希望有人参与到你的项目里来。通过使用标签给问题分类,开发者可以更方便地查看问题列表,从而节省时间。

3. 使用 GitHub 模板

使用问题模板和 PR 模板将给你带来很大好处,让开发者在提交 bug 和特性请求时使用标准模板可以让你获得足够的信息,以便在后续修复 bug 或开发新特性。

提交 bug 的通用指南

  • 提交 bug 之前首先需要:

  • 确保你运行的是最新版本的代码

  • 通过搜索功能确保同样的 bug 之前没有被提交过

  • bug 报告应该包含如下信息:

  • 概要:简单的问题描述

  • 重现步骤:你是如何发现这个 bug 的?如何重现?

  • 预期行为

  • 实际行为

  • 引用:相关 ticket 或信息来源的链接

  • 如果可能,添加一些包含可视化元素的附件文档,比如截屏、视频或图片

PR 的通用指南

  • 确保不存在要解决同样问题的 PR
  • 通过问题跟踪器查找相关的问题
  • 讨论需要作出哪些变更
  • 让别人知道你在解决这个问题
  • 在 branch 上开发,而不是 master
  • 提供有意义的 PR 描述
  • 遵循项目的提交规范
  • 写好你的 PR 描述
  • 在描述中加上问题链接

4. 使用命令行

控制台是我们的好朋友。在开发开源项目时,通过命令行来操作 GitHub 是最高效的一种方式。虽然有很多很好的 GUI,但都没有命令行那么灵活。还有一些非常好用的命令行工具,也只有使用这些工具才能让开发者如虎添翼:

  • **hub **对 git 命令进行了封装,可以用它拉取代码库、浏览项目页面、创建分支,甚至是提交 PR,这些操作都可以在命令行上完成。项目地址 https://hub.github.com
  • **tj/git-extras **是一组 git 工具,可用于查看代码库概要、更新变更日志、查看贡献者提交百分比等。项目地址 https://github.com/tj/git-extras

5. 遵循严格的提交规范

定义清晰的提交规范,并严格遵循,以下是一些通用指南:

  • 每一次修复作为单独的变更来提交
  • 提供有意义的提交信息
  • 在提交信息的第一行提供简短的描述。如果不明白为什么要这样做,看看 gitk 或 git log --oneline 命令的输出就知道了
  • 在消息体中包含问题的链接

6. 定义编码规范并配置预提交钩子

定义编码规范,并通过预提交钩子来强制执行这些规范,这样非常有助于写出具有可维护性的代码。只要遵循这些规范,不管是谁写的代码,它们看起来都具备了同样的风格,其他人在接手或维护这些代码时会更加省事。

推荐使用 Prettier 和 StandardJS,不过还有很多其他的选择,具体根据自己的情况而定。

typicode/husky 是一个很好的预提交钩子配置工具,项目地址 https://github.com/typicode/husky

7. 为 PR 配置自动化测试

对 PR 进行自动化功能测试、安全检查和代码风格检查是非常有必要的,但不应该通过手动的方式做。每当有 PR 提交时,持续集成服务器(如 TravisCI)可以在相应的 branch 上自动执行测试,这样可以防止开发者将未通过测试的 PR 提交到 GitHub 上。如果测试失败,GitHub 会在 PR 中显示一条消息,让提交者尽快修复问题。

TravisCI 文档 https://docs.travis-ci.com/user/pull-requests

8. 保护好 master,进行代码评审

GitHub 为保护 master 提供了可能性,避免代码直接提交到 master 上,或对其进行 rebase。当多人合作开发一个项目时,这点是非常重要的。另外,在将代码合并到 master 时,将代码评审作为必要的步骤。这个可以在每个代码库的 settings 页面进行配置。

保护好 master,并强制执行代码评审,你就可以高枕无忧,无需担心糟糕的代码会被合并到 master 上,也不会有人提交未经评审的代码。

9. squash 你的 PR

关于该使用 merge、squash 还是 rebase 存在很大的争议,不过我认为最好是使用 squash,理由是:

  • 不是所有的开发者都知道如何进行 rebase,大部分开发者都只是简单地在他们的变更之上合并 master。squash 避免了无用的合并信息和往 git 日志中添加噪音。
  • 不是所有的开发者都会遵循提交规范,squash 有助于控制合并到 master 上的提交信息。

为了更好地进行 squash,每个 PR 都应该属于某个特定的功能、bug 修复或任务。

10. 版本语义、标签、发布和自动化变更日志

版本管理对于软件来说非常重要,特别是在开源软件中,有很多其他项目可能会依赖你的项目。有了版本语义,我们通过版本号就可以知道某个版本是否包含了突破性变更,或者版本是否包含了新特性或 bug 修复。

版本格式通常是这样的 MAJOR.MINOR.PATCH:

  • 在做出不兼容的 API 变更时,增大 MAJOR
  • 增加向后兼容的新特性时,增大 MINOR
  • 进行向后兼容的 bug 修复时,增大 PATCH

我们还可以对这个格式进行扩展,加入额外的标签,作为预发布版本和构建元数据。

Conventional Commits 规范 建议基于提交消息引入一种轻量级的规范,与 SemVer 一起使用,让开发者在提交消息中提供与功能、bug 修复和突破性变更相关的描述。

TravisCI 有助于自动化这一过程 https://docs.travis-ci.com/user/deployment/releases

11. 使用标签钩子进行自动化部署

GitFlow 建议使用 release 分支进行发布,但这不是必需的。我们可以通过 git 标签获取要部署的文件,TravisCI 的文档 介绍了如何将 git 标签部署到 heroku 上。

其实很简单,只需要将标签属性设置为 true 就可以了。其他 CI 服务器的配置也类似。

我们可以在开发环境配置钩子,用于部署最新的 master 代码。我们也可以为每个 PR 创建临时的测试环境,不过这样做非常复杂,所以不一定要这么做。

12. 建立 GitHub 流式通道

这是一种非常方便的跟踪 GitHub 活动的方式,可以通过这种方式与其他人进行协作沟通。每个 GitHub 聊天室都会有通知流,GitHub 在 2013 年为此发明了一个新术语,叫作 ChatOps。

13. 自动化依赖更新

保持依赖更新是一项非常耗时的重复性工作,所以可以将它自动化。

所幸的是,有很多工具可用于保持依赖更新,它们会基于项目的最新版本创建 PR,然后自动执行非回归测试,如果测试通过,那么在合并 PR 后这些代码依然能够正常运行。不过如果有主版本变化,需要进行双重检查。

可以参考这两个工具:https://greenkeeper.iohttps://david-dm.org

14. 使用扩展来提升 GitHub 的 UI 体验

开源社区开发了很多非常有用的扩展,可用于提升 GitHub 的使用体验。可以通过 https://github.com/showcases/GitHub-browser-extensions 查看这些扩展。

15. 持续学习和改进

GitHub 和开源软件的开发实践一直在演化,我们需要关注 GitHub 的发布公告,并遵循开源社区的标准,跟上时代的发展步伐。


原文链接:15 Recommendations to Enhance your Github Flow
推荐阅读:Level UP! 提升你的编程技能

推荐阅读更多精彩内容