关于开源的几个真相!你还可能不如一枚小白精通开源

前言

Star多的项目就一定规范与优雅?文档是应放在wiki中还是code repo中?readme越简洁越好,还是越详尽越好?readme写中文还是英文?此文一网打尽,解读存在你脑海里的开源误区。记不住可是要分分钟被小白教做人哦!

腾讯开源沙龙邀请到了多位腾讯开源项目作者,其中近日开源的微信生物认证平台与标准TENCENT SOTER作者Henryye,以一个开源“小白”的身份,分享自己在开源路上踩过的“坑”。

嘉宾介绍

Henryye Henryye,叶轩,来自腾讯微信事业群,主要负责腾讯开源项目TENCENT SOTER生物认证平台的开发、维护与运营。

项目介绍

TENCENT SOTER TENCENT SOTER是腾讯于2015年开始制定的生物认证平台与标准,目前已经在微信指纹支付、微信公众号/小程序指纹授权接口等场景使用,并得到了验证。接入TENCENT SOTER之后,开发者可以在不获取用户指纹图案的前提下,在Android设备上实现可信的指纹认证,获得与微信指纹支付一致的安全快捷认证体验。 开源地址: https://github.com/Tencent/soter

以下是演讲实录:

TENCENT SOTER刚开源不久,我就能够受邀参加腾讯开源的沙龙分享,感到十分的荣幸。因此,我以开源“小白”的身份,分享我在开源过程中吸取的教训和经验。作为小白,不得不说踩“坑”真的很多,所以教训是放在经验前面的。

克服开源恐惧

以前,在我看来,GitHub只是用来膜拜大神,“借鉴”大神代码,用到自己的项目当中。当然我也尝试把自己写的代码放在GitHub上,但并没有很好地管理它,star只有个位数。我平时写代码的时候,没打算给别人看,只要自己能看懂就行,所以代码风格会比较粗放。我甚至还有“把fork当成star”的黑历史。我的同事实在看不下去了,提醒我:“这样做是会被人笑话的。”

TENCNET SOTER开源不仅是我的个人想法,也是公司层面的考虑。一开始做开源的时候,我是相当恐惧的,毕竟是“小白”,没有经验。但当我逐渐想通了以下几点,就不再惧怕开源了:

  • 开源是每个人都能做的事情 无论大神还是小白,都可以参与到开源当中,开源对任何人都是没有门槛的。小白把自己的代码贡献出去,社区开发者阅读过后,发现问题,进行反馈。对小白来说,开源不一定能得到“膜拜”,但一定能通过反馈优化代码。
  • 不过度在意star数 开源的本质是什么?比较谁的star数更多?Star数少了是不是就很丢人?肯定不是。好的开源项目,star数自然不会少。但如果舍本逐末,在项目质量都得不到保证的前提下就过度追求star数,那才真的很丢人。社区也不会欢迎这样的项目。
  • 给自己信心 这里要感谢下我的leader——kirozhao。从架构到代码,再到文档和演讲,kiro都事无巨细的对我进行指导,有他撑腰,我不再怀疑自己,这是我给自己的信心,更是kiro帮我建立的信心。
  • 开源提倡相互学习,走出舒适区 开源其实相互学习的过程,在微信开源Tinker、Mars等项目时,团队发现开源对微信产品的稳定性和功能丰富起到了很好的反哺作用。知道了这点,“小白”自然也不会惧怕开源了,反而更希望拥抱开源。

项目发布

下面介绍的这些,是我开源前从来没想过的一些问题。这些错误“小白”会犯,甚至是star数不少的开源项目作者也会犯一些错误。下面我们就一起来做几道选择和判断题。

  1. 文档是应放在wiki中还是code repo中? 我在整理代码的时候,发现repo中有90%以上都是HTML代码,同事都“嘲笑”我说“就像写了个前端项目”。实际上,我只是把生成的javadoc文件都放在code repo里面,造成了这样的假象。后期,我把一些项目文档,例如License,readme,contributing.md放在repo里面,而更详细的介绍,例如原理、安全接入指南等放在wiki repo 和 git pages里面。这样可以保持repo的清爽。
  2. 是否选择合适的代码检查配置? 每个编程语言都有不同的检查规范。代码检查配置,如Java的PMD在编译期间就已经做好,如果检查不通过的话,编译也是不成功的。这是保证自己代码质量的一种方式,不至于闹太大的笑话。
  3. 中英文之间是否有空格? 不同的字体有不同的显示,大部分字体中英文之间都不会去做空格处理。但实际上中英文之间有空格,整篇看起来在视觉上会更舒服,不至于太过散乱。
  4. Readme写中文还是英文? 答案是:根据目标用户选择。英文的readme是一定要写的,但中文Readme放在前面还是后面,要根据项目的目标用户决定。比如TENCENT SOTER主要面向国内用户,国外的手机并不支持,因此我们选择把中文放在前面。在中文readme最顶处留一个“for English version”的链接,可直接引到英文的readme介绍。但像WeFlow这些面向全球开发者或设计者的项目,最好中英文都有,实在精力有限也必须保留英文,而且要放在前面。
  5. Readme越简洁越好,还是越详尽越好? Readme写得太多,会让大家对项目望而却步。最好的做法是,告诉别人你的项目是什么,如果需要详细介绍,可以做链接,引导用户前往wiki或者自己的官网。还有做QuickStart,很明确地告诉用户怎样最简单地去使用我们的项目,给用户传达“噢,原来用你的项目这么简单,我也可以试一下”的信息。正因为“试一试”,你的项目就可能成为别人使用的目标。千万别给用户一种“繁文缛节”的印象。
  6. demo,你选择炫技还是易上手? 如果你的示例代码写得过于复杂的话,同样会让开发者望而却步。用户会觉得“哇,你的项目太高大上,我用不了”“你的代码太复杂,肯定效果不好”,或者开发者会怀疑人生,“是不是我能力不够”。这样你会白白流失一部分用户。

工具推荐

我还是小白,推荐的工具可能也比较入门。我推荐两个,在项目发布初期,我使用到的,个人感觉比较有意思的工具,比如shields和grammarly。

Shields大家都比较熟悉,用于生成项目徽章,相信大家都经常用到。Grammarly是帮助我们写英文文档的利器。它可以在编辑的时候自动提醒你,或者当你写完很长的英文文档后,把它放在Grammarly插件中,对拼写和语法进行检查,避免低级错误。

建造与维护

在项目的关注度方面,PR和自我PR都是很重要的过程。例如在知乎等比较大的社区推广你的项目,但前提在于,你对项目repo的质量有十足的信心。

其次,你需要及时解决issue。如果issue一直是open状态,项目会给用户负面的形象,用户会产生“你的代码写得不错,但为什么一直不维护呢?是不是以后都不维护了?”的疑惑,从而不得不放弃。用户还会根据你的commit活动来确定项目的更新状态与频率。

最后,你需要时刻记住,尤其是小白更加要留意,issue和pull request是无法删除的。所以你对项目做了什么事情,在社区说了什么事情,一定要谨慎,世界上是没有后悔药的。

点击链接可直接访问henryye的开源项目TENCENT SOTER(https://github.com/Tencent/soter) 哦~ 记得点个star,给我们的开源“小白”一个鼓励吧~

关注“腾讯开源”公众号,其他嘉宾的开源经验分享语录陆续放送,敬请期待!

原创声明,本文系作者授权云+社区发表,未经许可,不得转载。

如有侵权,请联系 yunjia_community@tencent.com 删除。

编辑于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏机器之心

业界 | 为什么Jupyter是数据科学家们实战工具的首选?

大型综合巡天望远镜(Large Synoptic Survey Telescope,LSST)坐落在智利安第斯山脉帕穹山脊,计划 2022 年启用。它将自动探测...

793
来自专栏java一日一条

高级Java程序员值得拥有的10本书

Java是时下最流行的编程语言之一。市面上也出现了适合初学者的大量书籍。但是对于那些在Java编程上淫浸多时的开发人员而言,这些书的内容未免显得过于简单和冗余了...

662
来自专栏iOSDevLog

github 十年历程2008年2009年2010年2011年2012年2013年2014年2015年2016年2017年2018年

3389
来自专栏ThoughtWorks

TW洞见〡大数据全栈式开发语言 – Python

文章作者来自ThoughtWorks:佟达 ,图片来自网络。 前段时间,ThoughtWorks在深圳举办一次社区活动上,有一个演讲主题叫做“Fullstac...

2905
来自专栏余果的专栏

面向未来的跨界开发技术(下)

设计不等于艺术。用文艺的话说就是“艺术发现问题,设计解决问题”。也即是说,设计为商业服务。作为上市公司的设计部门,需要清晰地展现产品,构建用户的渴望。在某种程度...

1.1K0
来自专栏惶心 - 技术博客

【Premium 文章】远行 要开心

从今天开始,博客将会不定期发布完全原创的文章,与博客其余大部分文章不同,这些文章属于惶心的个人文学创作,不属于技术类教程。想了半天,这类文章以后就叫【Premi...

1152
来自专栏CDA数据分析师

对自己的上网搜索记录进行爬虫是怎样一种体验

原作者 Walker Harrison 编译 CDA 编译团队 本文为  CDA 数据分析师原创翻译作品,转载需授权 前言 国外习惯用 Google 进行搜索,...

25010
来自专栏Java进阶干货

工作2年半跳槽面试阿里,成功拿到offer,凭什么?

2015年刚毕业的我,进入了一家小小的公司实习工作,在学校学了三年软件开发的我,还是想去寻找一份互联网行业的工作,这样更能学以致用发挥自己的特长。一直到18年三...

2311
来自专栏腾讯移动品质中心TMQ的专栏

管家12大版本质量把控秘籍

六脉神剑秘籍 说起一年一度的管家大版本,那可是一个浩大的工程,管家各大中心都会参与,变更代码线多,版本稳定期久,对各个中心正常的单周迭代需求合入影响大,这质量把...

2396
来自专栏潇涧技术专栏

Material on Mobile Development

1.Android开发者:http://developer.android.com/index.html Google官方Android开发者网站,发布关于A...

772

扫码关注云+社区