关于开源:开源最佳实践

转载自：https://github.com/LinuxSuRen…

为什么要编写这一份《开源最佳实际》呢？

首先，对于首次筹备尝试参加开源的人来说，很容易有无从着手的感觉。完事开头难，心愿这一份最佳实际能够帮忙更多无意参加开源的人们。不论你是一名一般的研发、还是一名非技术人员，参加开源必将使得你受益匪浅。

国内（中国）曾经有 Gitee 发动、泛滥开源爱好者独特编撰了《开源指北》，还有 GitHub 官网提供的《开源软件指南》，那这一份最佳实际和之有什么区别吗？开源不仅仅是把代码嗮进去就好了，更加重要的是一种合作精力的文化体验，以及具体落地操作。

与之不同的，本最佳实际更多会从落地实际的角度来讲述。

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

面对一个新的我的项目，尤其是在绝对不相熟的畛域，有如下的办法能够帮忙你提供后期的奉献：

文档奉献，这是十分无效的一种理解我的项目的形式，通常咱们能够在浏览文档的过程中，修复一些错别字、标点符号、语法错误、有效链接等等
good-first-issues，对于心愿收到更多奉献的我的项目而言，会在一些容易上手的 issues 上增加该标签

常见误区：

只有题目，没有内容
只有后果、景象，没有提供上下文
- 问题呈现的可能性千千万，没有人能猜到你的环境、操作步骤
只有截图，不提供谬误、异样、上下文的要害文字
- 没有文字的话，不便于其他人进行检索

最佳实际：

现有的 issues 中没有提到过该问题时再提交新的
相熟语言肯定要遵循对应社区冀望的规定
题目要简洁、标准
做好分类，能够通过标签或者题目前缀来分类
- 常见的题目分类法：Question: xxx, Proposal: xxx, Bug: xxx
和 UI 相干的 issues 要给出截图

常见误区：

应用繁多分支（例如：master）提交变更
单个 PR 中蕴含多个不同的优化、缺点修复
单个 PR 一直新增内容
合并本人提交的 PR
通过及时聊天工具督促特定的人 review 你的 PR

最佳实际：

首次提交 PR 前，浏览曾经胜利合并过的 PR 评论列表以及格局等
如果要修复的问题曾经有对应的 issue，请确保没有人提交对应的 PR，而后，请留言阐明你的修复打算
如果预计你提交的变更比拟多，请首先创立 issue，并根据具体情况（难易水平、争议性等）形容你的想法
一个 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 的人，并阐明是因为找不到其余的形式，以及示意道歉打搅

在 PR 的 review 过程中，通常会波及到三个角色的人：作者、维护者、其余。

首先，咱们要想明确一个问题——为什么要进行 review？不论 PR 中提交的是代码、文档还是其余类型的文件，进行 review 的都有着十分重要的意义。

开源最根本准则的体现，公开、通明
- 如果连 review 都不做的话，何谈开源？要公开的绝不仅仅是后果，更要害的是要公开过程
- review 相对不是审核的意思，任何人都能够是 reviewer，大家都有能够在这个过程中有所播种
生命周期
- PR 不适用于有紧急合并需要的状况
- 提交完 PR 后，作者首先应该自行查看一遍，如果发现还有问题的话，请标记为“进行中”
  - 咱们能够把还没筹备好 review 的 PR 的题目加上前缀：WIP:
  - 作者如果对某些代码（文档）不是很确定，能够间接把你的观点以评论的模式表述进去
- 在 2～7 天内实现 review 并合并
礼仪
- 没有人有任务对你的 PR 进行 review，包含维护者
- 每一位 reviewer 都对你的 PR 合并提供了帮忙，对他们表示感谢
- 在最佳的 review 周期内，不要去督促任何人对你的 PR 进行 review
- 如果的确须要申请 review 帮忙，请给出阐明，并且优先 @ 某个 team，其次才是间接 @ 某个人，并对打搅表示歉意
明确你的观点
- 尽量避免给出不置可否的评论，作者须要依据你给出的倡议来决定是否要进行批改
- 对于你不是很确定问题，能够这么表述：”我感觉这里可能有问题，给出倡议的做法以及理由，并指明该评论不妨碍 PR 的合并“
- 对于你很确定有问题的局部，给出能够证实你观点的信息或者数据，如果有相干权威材料的话，一并给出链接
  - 例如：PR 中代码正文不标准，给出官网社区的文档链接
自动化流程
- 利用相似于 Lighthouse 的自动化工具来治理 review 流程
- 合并之前尽可能多地运行自动化测试（单元测试、e2e 测试、压力测试等）
- 防止人为干涉自动化过程
- 如果 review 实现，但还须要一些人工验证的话，为防止过早主动合并，能够通过评论命令来妨碍
  - 例如：通过评论 /hold 来阻止机器人账号主动合并

对于社区（Community）这个词，不同的人有着不同的了解。本文的社区专指：开源社区（Open Source Community）。

在社区经营过程中，有很多好的实际和办法，例如：社交媒体、Meetup、SIG、TOC 等的经营。上面，给出局部组织模式的最佳实际领导。

确定 SIG 的准入准出制度，依据团队的理论状况来管制 SIG 的数量，经营的品质是首要思考的。

SIG 的衰弱倒退，离不开公开、通明、多元化等准则，流于形式的、不合乎开源精力的 SIG 没有存在的意义。

每次会议都要有会议开始和完结的表述
- 例如：当初开始咱们明天的例会；完结时能够说：“非常感谢各位加入明天的社区例会”等等的
激情地欢送首次加入例会的成员，并激励做自我介绍
做必要的上下文介绍
- 不论是拨入会议还是观看回放的人，都有可能是首次参加，短少上下文会导致他们难以明确相干探讨
- 如果有文字性的上下文介绍，尽量在会议记录文档中有体现
主持人要把控会议工夫、节奏
- 尽量管制在 1 小时内，未探讨完的议题放到下次探讨
- 在探讨过程中帮忙、疏导得出结论
应用适当的表述形式
- 防止应用相似于“咱们昨天探讨过 xxx”的表述，社区成员无奈理解到你们探讨的内容
确保例会的周期性
- 通常状况下，每两周一次的例会比拟适中
- 当参与者人数绝对较多，而且散布在不同时区的话，联合参与者的意见能够分两个会议
- 当能够主持会议的人都无奈加入，或者其余须要勾销例会的状况，尽早地告诉社区会议勾销
会议记录
- 文字记录，能够应用 Google Document 或者腾讯文档
- 会议录屏，依据会议参与者应用的语言不同，中文能够抉择哔哩哔哩，英文能够抉择 YouTube

还有一些其余的比拟举荐的习惯、办法：

习惯查看邮件
- 肯定要把本人罕用的邮箱地址关联到 GitHub 上，这样能力及时收到 issues 和 PR 中的互动信息
通过电脑、手机来治理本人的日程
- 开源社区总会有各种各样的会议，如果没有应用日历的习惯的话，非常容易忘记重要的事件

Google Engineering Practices Documentation

关于开源:开源最佳实践

为什么？

Get started

Issues

Pull Request

Review

社区经营

SIG 经营

SIG 会议

其余

其余参考