shaodahong/dahong

【翻译】如何为 Github 开源项目贡献代码？

shaodahong opened this issue · 0 comments

shaodahong commented

作者 Sarah Drasner 是一位开源社区非常活跃的程序媛，同时也是 Vuejs 团队的核心成员之一，本文并不会逐字逐句翻译，原文地址

本文旨在指导 Github 开源项目贡献之旅，前提条件

  1. 基本的 GIT 操作
  2. 一些基础的命令行知识

前言

实际项目中，我们会使用一些 Github 上面的开源项目，加快我们的开发进度，但是在开发中，有时候会遇到一些错误，它可能是个 Bug，或者满足不了我们的需求，在查看源码的过程中我们发现可能只需要一些改进就能大大的增强开发体验，但是我们无从下手，那么本文值得你一读

本文重点讨论给开源项目提交 pull request 流程，简称 PR

先读一读贡献指南

大部分的开源项目都欢迎其他开发者帮助贡献代码，而为了避免一次又一次的指导开发者熟悉项目开发流程，都会提供 CONTRIBUTING.md 文件或者在文档页面介绍 Contributing Guide，比如 Ant-Design

贡献指南包括

  • 代码风格规范
  • 提交 PR 前的一些检查
  • 项目的基础架构介绍

比如 Ant-Design 贡献指南 我们可以清晰的了解项目的基础架构和提交的一些规范

如果没有阅读贡献指南就进行代码修改，PR 提交，那么可能会导致你的开发体验很糟糕，花了三天的时间发现项目启动失败，然后自暴自弃，对贡献代码产生心理阴影，就算提交了 PR 可能也会分支错乱、重复 PR、代码不规范导致需要重新修改

所以如果开源项目提供了贡献指南，请找到它，读一读，你和维护者的时间都很宝贵

搜索很关键

在我们提交 PR 前先在 Github Issues 页面进行搜索（包括已打开和已关闭的），可能你要解决的问题有其他人提起过，对于未解决的历史原因我们应该要了解，避免重复劳动

a65cf5b609fa1c5b10ce6676bbb06a6

提交 Issue

提交 PR 前最好的做法是先提交一个 Issue，围绕 Issue 来进行 PR，Issue 是一个背景描述

提交 Issue 最好简洁明了，避免附带个人情绪，比如你实际项目开发中受阻，一肚子气发个 Issue 叫做 这个垃圾项目也有人用？ 或者 erfoihero（一通乱打），这并不会带来一些实质的解决方案，你的开发还是会受阻，肚子里的气也不会消

我们应该围绕遇到的问题提供必要的信息

  • 遇到 Bug

    • 相关的操作环境（系统版本，软件版本等）
    • 复现步骤
    • 简单的 Demo

  • 新功能

    • 解决了什么问题

  • 其他

    • 代码重构
    • 功能优化
    • 等等

为什么要这么做？想一想你要请别人吃饭，你也会询问别人能不能吃辣，或者有什么忌口吧，不然胡乱一通操作，不欢而散

提交前的准备

如果 Issue 得到维护者的赞同，那么你可以着手开发了，但是我们在初次 PR 前总会考虑的不够多，比如修改不相关的一些代码，通常出发点是好的，但是会造成维护者的困扰，修改的代码越多，Review 的困难度也会越大，如果你修改的代码不涉及你要提及的 Issue，尽量避免改动，或者重新发起一个 PR

提交 PR

Fork

第一步我们先将项目克隆到我们自己的仓库

5742a65e80535488aa01adaafebd1a1

本地开发

# 拉取项目
git clone https://github.com/YOUR-USERNAME/YOUR-FORKED-REPO.git

# 进入项目文件夹
cd YOUR-FORKED-REPO

# 添加上游分支（为了保证自己仓库的代码和开源项目的代码同步）
git remote add upstream https://github.com/ORIGINAL-DEV-USERNAME/REPO-YOU-FORKED-FROM.git
git fetch upstream

# 切一个新的分支进行开发（良好的习惯）
git checkout -b GOOD-FORKIN-NAME

完成开发工作，提交代码，为了让 commit message 更具有语义化，一般使用 conventional-commit 格式

git add -A
git commit -m “ADDING IN A TACO DISPENSER”
git push origin GOOD-FORKIN-NAME

提交

这时候浏览器打开开源项目的仓库或者我们自己克隆的仓库应该就会看到有新的 PR 可以提交
8777489bbe77b0c4a3875d211e5f0e1

按照步骤操作，我们还可以使用特定的回复标签关联 Issue，比如 Fixed #ISSUE-ID

9a39fc6344cfb498f79c3bacb69be3d

最后

到这一步基本的开发和提交工作已经完成了，维护者会对你的 PR 进行 Review，如果没有问题那么就会合并到主干等到版本发布就行了

如果需要代码修改，直接在本地的分支开发后提交就可以了，相关的修改会自动同步到 PR 中

或者你的代码需要和开源仓库的同步，那么可以

# 拉取上游分支最新的代码
git fetch upstream

# Rebase 合并上游代码
git rebase upstream/master(或者其他主干)

对于大型的开源项目来说，你的 Issue 或者 PR 可能不会这么快的得到反映，毕竟开源项目都是一些维护者下班闲暇时间开发的，所以耐心等待……