关于开源:开源最佳实践

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

为什么？

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

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

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

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

Get started

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

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

• 文档奉献，这是十分无效的一种理解我的项目的形式，通常咱们能够在浏览文档的过程中，修复一些错别字、标点符号、语法错误、有效链接等等
• good-first-issues，对于心愿收到更多奉献的我的项目而言，会在一些容易上手的 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 只能蕴含一类批改
• 每次提交都须要新增一个分支进行

• 防止同一个主题的 PR 重复敞开、新建

  • 防止在同一个 PR 中频繁地提交，这对于 reviewers 来说将会是极大的困扰
  • 如果你的 PR 还没有筹备好承受 review，请在题目上增加前缀 WIP: ，直到你自测充沛
  • 在依据 reviewers 提出的倡议进行批改时，防止应用强制推送 --force，这对于 reviewers 来说将无奈轻松地看到你最新的批改局部
  • 尽可能放弃你的 commit 记录比拟优雅，万一屡次 review 后的记录比拟多的话，我的项目 owners 会在合并时决定是否会 squash 你的提交记录

• 尽可能多地给出以后 PR 的详情，包含但不限于：相干 issues、解决的问题、任何不便 review 的上下文

  • 波及到 UI 的改变，给出批改前后的成果截图
  • 视状况给出你的自测过程
  • 对于可能引起争议的局部，给出你的解释

• 如果你的 PR 超过一周没有失去 review，能够尝试 cc 相干的 team

  • 如果没有相干的 team 能够 cc 的话，能够找最近合并过相似 PR 的人，并阐明是因为找不到其余的形式，以及示意道歉打搅

Review

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

SIG 会议

• 每次会议都要有会议开始和完结的表述

  • 例如：当初开始咱们明天的例会；完结时能够说：“非常感谢各位加入明天的社区例会”等等的
• 激情地欢送首次加入例会的成员，并激励做自我介绍

• 做必要的上下文介绍

  • 不论是拨入会议还是观看回放的人，都有可能是首次参加，短少上下文会导致他们难以明确相干探讨
  • 如果有文字性的上下文介绍，尽量在会议记录文档中有体现

• 主持人要把控会议工夫、节奏

  • 尽量管制在 1 小时内，未探讨完的议题放到下次探讨
  • 在探讨过程中帮忙、疏导得出结论

• 应用适当的表述形式

  • 防止应用相似于“咱们昨天探讨过 xxx”的表述，社区成员无奈理解到你们探讨的内容

• 确保例会的周期性

  • 通常状况下，每两周一次的例会比拟适中
  • 当参与者人数绝对较多，而且散布在不同时区的话，联合参与者的意见能够分两个会议
  • 当能够主持会议的人都无奈加入，或者其余须要勾销例会的状况，尽早地告诉社区会议勾销

• 会议记录

  • 文字记录，能够应用 Google Document 或者腾讯文档
  • 会议录屏，依据会议参与者应用的语言不同，中文能够抉择哔哩哔哩，英文能够抉择 YouTube

其余

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

• 习惯查看邮件

  • 肯定要把本人罕用的邮箱地址关联到 GitHub 上，这样能力及时收到 issues 和 PR 中的互动信息

• 通过电脑、手机来治理本人的日程

  • 开源社区总会有各种各样的会议，如果没有应用日历的习惯的话，非常容易忘记重要的事件

其余参考

• Google Engineering Practices Documentation