如何创建一个开源项目 | GitHub 开源指南系列之二


Section 1    

什么是开源,为什么要开源

你是否正在考虑开始参与开源?那么恭喜你!世界将赞赏你的贡献。不过我们需要先来谈谈开源是什么,以及人们为什么这样做。


 开源是什么意思?

当一个项目被开源,这意味着任何人都可以出于任何目的查看,使用,修改和分发你的项目。 这些权限通过开源许可强制实施。

开源是强大的,因为它降低了事物被采纳的障碍,允许想法迅速传播。

要了解它的工作原理,想象你的朋友组织了一场聚餐,而你带去了一个樱桃派。

* 每个人都尝了那个派(使用)

*  派的味道棒极了!大家请你分享它的配方(view)

*  一个叫 Alex 的朋友是个糕点师,他建议少放点糖(modify)

*  一个叫 Lisa 的朋友想要用它作为下周的晚餐(distribute)

相比之下,一个闭源过程就像去一家餐厅订购一个樱桃派。你必须为了吃饼支付费用,餐厅恐怕不会给你他们的食谱。如果你准确地复制了他们的馅饼,并以你自己的名义出售,餐厅可以对你采取措施。

人们为什么把他们的作品开源?


我从开源使用和协作中获得的最有价值的经验之一,就是在我面临许多与其他开发人员相同问题的过程中所建立的联系。

— @kentcdodds, “参与开源对我来说太棒了”‍ 

个人或组织为何想要开源一个项目,有各种各样的的原因,例如:

协作:开源项目可以接受世界各地人们的修改。就像 Exercism 就是一个拥有350多个贡献者的练习平台。

采用和重组:任何人几乎可以出于任何目的使用开源项目。人们甚至可以使用它来构建其他东西。例如,WordPress 就是派生自一个名为 b2的现有项目。

透明度:任何人都可以检查开源项目是否有错误或不一致。透明度对保加利亚美国等政府,银行或医疗保健等受监管行业以及 Let' s Encrypt 等安全软件都很重要。

开源并不仅仅限于软件。你可以开源任何事物,从数据集到书本。

可移步 GitHub Explore 去找找看,有什么是你可以开源的。

开源是指“免费”吗?

开源最大的吸引之一是它不花钱。 但是,“免费”只是开源的总体价值的一个副产品。

因为开源许可证要求任何人可以几乎出于任何目使用,修改和共享你的项目,项目本身往往是免费的。 如果该项目花钱使用,任何人也都可以合法地复制和使用免费版本。

因此,大多数开源项目是免费的,但“免费”不是开源定义的一部分。 有些方法可以通过双重许可或有限功能间接地为开源项目收费,同时仍然遵守开源的官方定义。

Section 2

我是否应该发起我自己的开源项目?

简单来说,答案是肯定的,因为无论结果如何,启动你自己的项目来了解开源的工作原理是一个好方法。


如果你从来没有创建过一个项目,你可能会担心人们会说什么,或者是否有人会注意到。 如果这听起来像你现在的状态,别担心,你并不孤独!

开源工作就像任何其他充满创意的活动,无论是写作还是绘画。 向世界分享你的作品会让你提心吊胆,但唯有练习能够让你的感觉变好的方法 - 即使你没有观众。

如果你还不确信,请花一点时间思考你的目标可能是什么。

设置你的目标

目标可以帮助你弄清该做什么,不应该说什么,以及你在哪方面需要其他人的帮助。 首先问自己,我是为什么开源这个项目?

这个问题没有标准答案。 对于一个项目你可以有多个目标,或者具有不同目标的不同项目。

如果你唯一的目标是炫耀你的工作,你甚至可能不需要他人的贡献,甚至在你的 README 中说明这点。但另一方面,如果你需要贡献者,你会投入时间来使文档清晰,好让新的参与者感到欢迎。


在某些时候,我创建了一个自己正在使用的自定义 UIAlertView,我决定将它开源。所以我修改它使其更有活力,并把它上传到了 GitHub。我还写了我的第一个文档,解释给其他开发人员如何在他们的项目中使用它。很可能没有人会去使用它,因为它是一个简单的项目,但我的贡献让我感觉很好。

— @mavris,自学的软件开发者:为什么开源对我们那么重要

随着你的项目增长,你的社区可能不仅需要你的代码。回应问题,审查代码和传播你的项目都会成为开源项目中的重要任务。

而你在非编码的任务上花费的时间将取决于项目的大小和范围,你应该准备好作为维护者来自己解决或找人帮助你。

如果你是公司开源项目的一部分, 确保你的项目有它需要茁壮成长的内部资源。 你需要确定谁在启动后负责维护项目,以及如何与你的社区共享这些任务。

如果你需要专门的预算或人员来促进,操作和维护项目,请尽早提出。


当你开始开源一个项目时,确保你的管理流程考虑到你项目周围社区的贡献和能力很重要。不要害怕让那些没有在你的企业中受雇的贡献者参与项目的关键部分 - 尤其如果他们是频繁的贡献者的话。

— @captainsafia, “所以你想开源一个项目,是吗?”‍

加入其他项目

如果你的目标是学习如何与他人合作或了解开源的工作方式,请考虑为现有项目做出贡献。从你已经使用并喜欢的项目开始。像修复拼写错误或更新文档简单的事也能为项目做出贡献。

如果你不知道如何开始作为贡献者,请查看如何为开源做贡献

Section 3

发起自己的开源项目

即使你没有很好的时间来开源你的工作。你也可以开源一个想法,正在进行中的工作,或是关闭了多年的源码。


一般来说,如果你乐意于他人对你工作的查看和反馈,你就应该开源你的项目。

无论你决定开展项目的哪个阶段,每个项目都应包括以下文档:

#    开源许可证

#    README

#    贡献者指南

#    行为准则

作为维护者,这些文档可以帮助你指导他人,引导他人,表达你的期望,管理贡献并保护每个人的合法权益(也包括你自己的)。它们能够大大增加项目成功的机会。

如果你的项目在 GitHub 上,则将这些文件放在你的根目录中,并使用推荐的文件名将有助于 GitHub 识别并自动将其显示给读者。

选择一个许可证(license)

开源许可证保证其他人可以使用,复制,修改和贡献给你的项目,而不会产生不良后果。 它也可以保护你免受繁琐的法律影响。启动开源项目时,请务必包含许可证。

法律工作是非常无趣的。但好消息是,你可以将现有许可证复制并粘贴到存储库中。只需要花这么一点时间,就能保护你的辛苦工作。

MITApache 2.0, 和 GPLv3 都是非常流行的开源许可证, 但你可以选择其它的许可协议.

当你在GitHub上创建新项目时,你可以选择许可证。包括开源许可证将使你的 GitHub 项目成为开源。

如果你在管理开放源码项目的法律方面有其他问题或疑虑,本指南也专门针对法律部分做了介绍。

编写自述文件(README)

自述文件不仅仅是用于说明如何使用你的项目。他们还可以解释你的项目为什么重要,以及它可以为你的用户做什么。

在你的自述文件中,尝试回答以下问题:

#    这个项目做什么?

#    此项目解决了什么问题?

#    如何开始?

#    如果需要,我可以在哪里获得更多的帮助?

你可以使用自己的 README 回答其他问题,例如贡献流程、项目目标以及许可证和归属信息等等。 如果你不想接受他人的贡献,或者你的项目尚未准备好作为产品提供使用,那么也请将这些信息写下来。


更好的文档意味着更多的用户,更少的求助和更多的贡献者等等。要记住,你的读者不是你自己!来到项目中的每个人可能有着截然不同的经历。

— @limedaring, “写好给他人看的文档(视频)”‍

有时,人们会因为觉得项目未完成而不愿意撰写 README,或者他们不希望做出贡献。这些都是写一个 README 的很好的理由。

想要获得更多灵感,请尝试使用 @18F 的 “让 README 可读” 或者 @PurpleBooth 的 README 模板来撰写一个完整的 README。

当你在根目录中包含一个 README 文件时,GitHub 会自动将其显示在存储库的主页上。

编写你的贡献指南

贡献指南,内容就是是告诉你的受众如何参与你的项目。例如,你可以照以下内容来撰写:

#    如何提交错误报告(尝试使用issue 和 pull request 模板

#    如何建议一个新功能

#    如何配置你的环境和运行测试

除了技术细节, 贡献指南也是一个供你传达对贡献者期待的机会, 例如:

#    你所寻求的贡献者类型

#    你项目的路线图或者版本

#    贡献者应该(或者不应该)如何与你取得联系

温柔友好的逾期和向贡献者们提供具体的建议(例如写文档或者搭建一个网页)能够有效地使新人感到受欢迎,并乐于参与其中。

例如,Active Admin 以这样的方式开始它的贡献指南

首先, 非常感谢你考虑为 Active Admin 贡献帮助。正式你这样的人们使得 Active Admin 成为了如此优秀的工具。

在你项目开始的初期,你的贡献文件可以很简单。你应该经常解释如何提交错误和文件问题,以及关于如何作出贡献的技术问题(例如测试)。

随着时间的推移,你应该增加其他常见问题到你的贡献指南中。写下这些信息也就意味着问你相同问题的人会越来越少。

想要获得更多有关编写贡献文件的方式,请查阅 @nayafia的 贡献指南模板或者 @mozilla 的 “如何构建 CONTRIBUTION.md”。

在 README 中要撰写贡献者指南的链接,这样更多人就能看到他。如果你在你的项目中放入了贡献者指南,当一个贡献者创建 issue 或者开启一个 pull request 时,GitHub 会自动链接你的文件。

建立行为守则


我们都有过这样的关于重复劳动的经验,无论是维护者试着解释为什么某些事物必须通过某种明确的方式执行,或者是用户…提出一个简单的问题。行为守则成为一个便利的参考和可链接的文档标明你的团队会认真对待具有建设性的讨论。

— @mlynch, “让开源成为一个有趣的地方”‍

毕竟,行为守则是有助于为你项目的参与者提供一个整体规范和约束的。这在你为社区或公司推出开源项目时尤其凸显它的价值。一份行为守则可以帮助促进社区的健康发展,拥有建设性的社区行为,会大大减轻你作为维护者的压力。

更多信息,请参见 行为守则指导

除了传达你期待参与者如何行动,行为守则也倾向于描述这些期待针对谁,适用于何时,以及对于违规行为的处理方法。

就像开源许可证一样,有现成的行为守则,所以你不必自己编写。贡献者公约是一个行之有效的行为守则,已经被用在超过4000个开源项目,包括 Kubernetes,Rails,以及 Swift。无论你使用哪一种,你都应该准备好在必要时执行行为守则。

将文本直接粘贴到项目存储库中的 CODE_OF_CONDUCT 文件中。将文件保存在项目的根目录中,以便轻松找到,并从 README 中链接到它。

Section 4

为项目命名及设立品牌

品牌不仅是一个华丽的logo或者易记的项目名。它还关于你如何谈论你的项目,以及你想把信息传递给谁。


选择正确的名字

选择一个容易记住,有创意,能表达项目用意的名字。例如:

#    Sentry 监控应用程序的崩溃报告

#    Thin 是一个简单快速的Ruby web服务器。

如果你的项目是基于一个已存在的项目创建,那么使用他们的名字作为你项目名的前缀会帮助你阐述你项目的用途。 (例如 node-fetch 将 window.fetch 添加到了 Node.js)。

考虑阐明所有。押韵虽然有趣,但是记住玩笑不可能转变成其它的文化,或者他人与你有不同的经历。你的一些潜在用户可能是公司员工,你不能让他们在工作中很难解释你的项目!

避免命名冲突

查看是否有同名的开源项目,尤其是你分享的是同样的语言或者生态系统。如果你的名字与一个已存在的知名的项目有冲突,你会让你的粉丝感到困惑。

如果你想要一个网站,Twitter账号或者其他特性来展示你的项目,先确保你能得到你想要的名字。理想情况下,为了美好的未来现在保留这些名字,即使你现在不想用他们。

确保你的项目名没有侵权。如果有侵权,可能会有公司要求你的项目下架,或者对你采取法律措施。这样得不偿失。

你可以查阅 WIPO 全球品牌数据库避免商标冲突。如果你是在公司工作,法律团队会帮你做这件事

最后,去谷歌搜索你的项目名。大家会很容易地找到你的项目吗?在搜索结果礼是否有你不想让大家看到的东西?

你的写作(和代码)如何影响你的品牌

在项目的整个生命周期中,你需要做很多文字工作:README,教程,社区文档,回复 issue,以及处理很多的邮件列表。

是否是官方文档或者一封普通的邮件,你的书写风格都是你项目品牌的一部分。考虑你可能会拥有粉丝,以及这是你想传达的声音。

我尝试处理每一个细节,包括:处理邮件,展示示例,友好待人,认真处理大家的issues以及试图帮助到大家。经过一段时间后,大家可能不再是只问问题,还会帮助我解决其他人的疑问以及给我喜悦,他们模仿我的风格。

— @janl on CouchDB, “Sustainable Open Source

使用热情,通俗易懂的语言(如“他们”,即使是指一个人)能够让新来的贡献者感觉项目非常欢迎他们。使用简单的语言,因为你的读者可能英语水平一般。

除了书写风格外,你的编码风格也是你项目品牌的一部分。 AngularjQuery 这两个项目的代码风格均是不错的示例和向导。

当你的项目才开始时,没有必要为项目编写一份风格指南。你可能会发现你喜欢将不同的编码风格融入到项目。但是你应该想到你的书写和编码风格会吸引或者拒绝不同类型的人。项目的早期是你建立你希望预见先例的机会。

Section 5

发起项目之前的检查项

准备好开源你的项目了吗?有一份帮助检查清单。检查所有内容?你准备开始吧! 点击 “publish”,然后保持内心平和。


文档

#    需要为项目选择一个开源许可证

#    项目要有基础文档 (README, CONTRIBUTING, CODE_OF_CONDUCT)

#    易记的项目名,指出项目是做什么的,不能和已存在的项目冲突或者商标侵权

#    最新的 issue 队列,组织和标记清楚的 issue

代码

#    项目使用一致的代码风格和明确的功能/方法/可用的名字

#    注释清晰的代码,记录意图和极端情况

#    在修改历史、issue 或者 pull request 中没有敏感的信息 (例如 密码或者其他不能公开的信息)

如果你是代表个人:

#    你已经告诉了你的法律部门,以及/或者理解了你公司(如果你是某一家公司的员工)的开源政策和IP

如果你有一家公司或者组织:

#    你已经告诉了你的法律部门

#    你有一个宣布和促进项目的营销计划

#    一些人被允许管理社区互动(回复issues,检查和合并pull requests)

#    至少有两人管理访问项目

section 6

你做到了!

恭喜你开源了你的首个项目。不论结果如何,对开源社区都是一份礼物。随着每次 commit,comment 和 pull request,你正在为自己或者他人创造学习和成长的机会!

©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 194,524评论 5 460
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 81,869评论 2 371
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 141,813评论 0 320
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 52,210评论 1 263
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 61,085评论 4 355
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 46,117评论 1 272
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 36,533评论 3 381
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 35,219评论 0 253
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 39,487评论 1 290
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 34,582评论 2 309
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 36,362评论 1 326
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 32,218评论 3 312
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 37,589评论 3 299
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 28,899评论 0 17
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 30,176评论 1 250
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 41,503评论 2 341
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 40,707评论 2 335

推荐阅读更多精彩内容