打造GitHub千星项目的经验分享


Alt textProduct Hunt链接官网链接 <-- 戳戳我 下载页面 GitHub项目

2017年初,我花了大约三个星期写了基于Electron的GitHub Gist管理软件。开始只把它作为学习Electron的练习项目,却想不到它意外火了一把。

正式发布后,在GitHub的星数在一周左右冲上了1000,连续好几天登上了GitHub daily trending的前十(JS和All language)。在收到不少有意思的Issue和PR之余,还被Slack一个高级工程师引荐加入Electron官网的feature app之一。甚至还被一些国外媒体自发报道。(这里、这里、和这里)


Alt text

网上关于在GitHub上打造高星项目的经验分享不多,少数几篇也是巨牛级别的,让人学习起来无从下手。所以我想把这次有意思的经验写下来和大家分享。

Lepton介绍


Alt text

是一款跨平台(Mac/Windows/Linxu)的snippet管理软件,简单来说,“码笼”。

功能

查询/新建/修改/删除 Snippet本地搜索 语言标签 + 个性化标签格式化Description(title + tag)Markdown渲染富文本编辑语法高亮 云端同步 + 跨平台支持(Win + macOS + Linux)项目开源

初衷

项目的初衷是打造一款保存snippet的“印象代码”。

作为一名码匠,平时需要把总结的snippet保存在易于管理的地方,就像平时把笔记保存在印象笔记里一样。如果印象笔记能保存snippet就好了!可惜印象笔记对代码块支持不好,需要在别的地方把代码块高亮,然后再贴回来,并常常出现格式混乱。

我们也可以使用Google Drive/Dropbox/其他云盘。缺点是,这种基于文件夹的管理不如标签适合检索。还有一些单机软件比如Snippets, 能实现本地代码保存,可惜不支持跨平台同步(比如从Mac到Windows)。

到2017年初为止,GitHub Gist可能是最适合保存snippet的云端。它不仅支持基本的语法高亮、分享、隐私设置,还会保存代码的所有历史版本,甚至还提供了REST API支持。美中不足的是,Gist没有提供标签功能,而且网页端开发不完善,所有snippet按照时间顺序堆积在一起,难以有效管理。虽然有少数第三方的客户端,比如GistBox,但是都闭源且开发停滞。所以,我觉得利用Electron + Gist打造跨平台的snippet manager将是一个不错的切入点。

技术调研

项目开始前,我在Electron feature app网页上寻找里面的开源项目,希望可以借鉴经验,少踩坑。

幸运的是,我在找到了一个技术栈相似的项目pupaFM。作者xwartz提供了详尽的commit记录,阅读commit记录就像阅读历史故事一样有意思 。通过在本地重现pupaFM大概前60个commit,我大致了解了Redux+React+Electron搭建项目的基本方法,也同时点亮Webpack技能点。

就是在这个基础上搭建起来的。为了方便其他开发者方便借鉴经验,我尽可能保证commit记录的可读性,代码里也提供详细的comment,以传承好开源精神。

社区支持

毫不夸张地说,项目不是闭门造车,它在开发阶段从中获得了很大的支持。2016年底时候,社区中的成员1MHz刚发布了他同样基于Electron的作品Knotes,并在社区中分享了他的开发经验,我读后很受启发。向1MHz请教后,他对的开发提出了很多中肯的建议,尤其是UI库选择和自动更新这两个地方;)

大概两周后,框架和基本功能初具雏形,我从太阁程序员社区又邀请到了首批内测用户,得到很多有意思的反馈。(尤其感谢meilinz、Aaronice、1MHz、hongbojing、blukpine)

我这次把项目经验总结成文,也是为了对太阁社区回馈:)

技术实现

所选用的框架是Electron。Electron把Node.js和Chromium两者结合,开发者可以使用JavaScript进行跨平台的桌面APP开发。同时,项目还选用React + Redux来构建前端UI和管理App的状态,并使用Webpack来作为构建工具。


Alt text

下面将讨论一些技术实现上的细节。

代码高亮

采用Highlight.js来进行代码的语法高亮。由于Highlight.js作者很傲娇地不支持line number,我正好利用这个机会学习这技术。下面是最终效果图。


Alt text

代码分行

如上图,代码块放在了一个HTML table中。首先用正则式/\r?\n/把代码分行,并同时计算每行对应的line number。line number放在上面HTML Table中的第一列,代码放在第二列。使用Table的好处是,当某行代码太长导致一行放不下而被迫折返时,它不会进入line number的列中。下面是不使用Table时可能会遇到的问题。


Alt text

不要复制line number

有时候,我们在网上复制代码时,会碰到误选line number,导致如下图中line number也一同被复制的现象。


Alt text

的解决方案是采用data-pseudo-content来标记行数,避免了line number被误选复制的问题,效果妥妥的!


Alt text

下面奉上snippet。详细代码请看这个gist。

  let lineNumber = 0  const contentTable = adaptedHighlightedContent.split(/\r?\n/).map(lineContent => {    return `<tr>              <td class='line-number' data-pseudo-content=${++lineNumber}></td>              <td>${lineContent}</td>            </tr>`  }).join('')  // 最后输出:`<pre><code><table class='code-table'>${contentTable}</table></code></pre>`

Markdown渲染

采用marked模块进行Markdown渲染(Markdown 转换为 HTML)。感兴趣的话,大家也可以亲自做一款markdown editor!

var marked = require('marked');console.log(marked('I am using __markdown__.'));// Outputs: <p>I am using <strong>markdown</strong>.</p>


Alt text

React + Redux state

开始时,我曾把一些Dialog的show/hide作为React component的local state来处理。当时我认为它们和app的全局state无关,应该放在component中。后来,随着dialog数目的增多(search/create/edit/delete/logout),属于不同component的dialog出现了相互覆盖、难以协调的现象。最后我不得不把它们改回全局的redux state。这是一点小经验。

标签实现

GitHub Gist本身不支持标签。我一开始想法是通过一个secret gist来保存和同步标签。后来发现这个方法有些问题。

    效率不高,每次标签变化都要把所有标签记录重新写入这个secret gist,而且出错后容易丢失记录,最后弃用。开发者不应该在没有得到用户同意的情况下,私自使用secret gist来存储数据。任何关于gist的改动都应有用户来做决定。

目前方法是通过description部分的特殊字符#tags来保存自定义的标签。优点是标签分散到每个gist中,每次只需要更新该gist对应部分的标签即可,可以同步到云端。而且它可读性高,即使用户有一天抛弃转回原生的网页端,也能轻易读懂description的信息。


Alt text
Alt text

UI设计

图标


Alt text

作为程序员,能把图标制作到这个程度我是很满意的了...

意思是轻子,是指不参与强相互作用的自旋为ћ/2 的费米子,其中电子Electron是最出名的轻子。项目起名Lepton,是对Electron框架的致敬。(这一系列的项目爱用物理粒子起名,比如Electron、Atom、Photon等)

开始时候,曾想用β衰变图(β衰变会产生两种轻子)来作为图标,可惜总画不好。后来退而求其次,总能画个圆形图案表现出粒子感吧(其实用圆形表示轻子是很不科学的),最后在写轮眼的启发下,有了现在的设计。

图标的制作方法简单、成本低、时间短,但效果不错。具体而言,先用系统自带工具画一个逗号,然后去下面第一个网站把图片转换成svg,然后再去第二个网站把svg文件转换成Material风格的图标。即使来回折腾几遍也就是半小时的事情。

下面奉上网站链接:

http://pngtosvg.com/https://android-material-icon-generator.bitdroid.de/

界面设计

的界面几乎没有设计,我很克制地不去添加不必要的元素。

之前做的项目(比如这个,和这个),由于设计过度,到后来已有点驾驭不了。这次吸取经验, 能用Bootstrap原色就用原色,能不添加button就不添加button,能用黑白就不用彩色。这样下来,不仅节省了时间,界面反而被人称赞好看。有时开玩笑,说灵感来自清水混凝土。

CodeMirror

CodeMirror是一款第三方的text editor,提供了很多非常棒的编辑功能。(比如代码块的collapse/expand、语法高亮)


Alt text

来自的wujysh在把CodeMirror集成到上做了非常出色的工作!正是因为有他的贡献,原来蹩脚的text editor进化为了现在的代码编辑利器。

同时他在对产品的使用和布局上也提出了很多出色的见解;)

本地搜索

早期曾经使用elasticlunr.js来实现本地搜索。遗憾的是,它目前只支持英文的整词搜索,比较鸡肋。后来我改用了fusejs,华丽丽地支持partial search和中文,搜索功能瞬间满血复活。


Alt text

遗憾的是,并不支持对代码部分的搜索,具体技术上的原因可以参考这个Issue。目前支持搜索的部分是:description、文件名、tags

自动更新

Electron自带了一个autoUpdater模块,可以自动检测server上的新版本,并自动在后台下载。

并没有直接使用自带的autoUpdater,而是使用electron-builder集成的更新模块。每次release时候,electron-builder会把打包文件以及带有版本信息的meta data文件上传到GitHub的release页面。当打开时候,它会自动检测release页面上的最新版本信息,若发现有新版本,便会提醒用户下载。

注意,当发布到Mac App Store时候,必须要关闭这些auto updater的功能。

项目推广

说明文档

任何一个GitHub项目都应该有一份完善的说明文档,以方便别人了解这个项目。我个人的习惯是,即使项目做不完,也会把做不完的原因和目前的进度在说明文档上写清楚,做到有始有终。

这是我写说明文档的一些例子:例子1、例子2、例子3。

的早期成功得益于较为完整的文档,不少用户还对文档内容提出了改进的建议。这里奉上曾经总结过的写说明文档的资源。

初次亮相

项目一开始放在了V2EX社区上发布,获得了很不错的反馈,非常感激。在各位热心用户的反馈下,从最初只支持查看gist的简单客户端,逐步发展成为集 Tag + Search + CRUD 一身的APP。现在可以很不夸张的说,目前的很多用户体验要优于基于网页客户端的GistBox。

早期获得的关注帮助它连续好几天进入GitHub的daily trending,这为它吸引了很多国际开发者的关注。(这是我后来才发现的,一开始还很好奇这些国际友人从哪里听说)

开源合作

在GitHub上获得不少开发者的贡献,下面一并感谢:

wujyshmeilinzlcgforeverCalinourogersachan

后续思考

毫无疑问,这是一个很有趣的经历,不仅仅是积累了很多技术(在开发过程中,我自己就使用记录了大量的gist),还在产品上有了更多的思考。

项目开发前两周,我所有注意力都集中到集成GitHub API、完成基本的CRUD功能上,我所关注的是HOW。当进入第四周到第五周,产品核心功能(Tag + Search + CRUD)逐步完善,受到关注越来越多,我更多思考这个项目是什么(WHAT)。我是要把GitHub自带的Gist网页端复制到桌面吗?还是通过自建一个snippet生态?我们应该如何取舍平衡功能呢?

我的结论是,要成为能保存代码的印象笔记,姑且理解为“”。它的终极目的是以开源本身来回馈开源社区;它的直接手段是帮助程序员有效利用收集的点滴智慧(读作dai ma),在抱StackOverflow大腿之余,也能够抱自己大腿。所以,我在新功能的取舍上以下面“三个有利于”作为衡量标准:

    是否有利于用户收集代码 (比如引入CodeMirror)是否有利于用户便捷获取代码 (比如引入Local Search、copy/share button)是否有利于用户专心分析代码 (比如 Immersive mode)

并且在社区的帮助以及自己时间允许范围内进行。

最后,这段经历告诉我们,打造一个GitHub上千星项目,过程其实没有那么神秘,重点在于清晰的项目目标和乐于分享的精神。

致谢

一年前参加了太阁程序员社区,从里面的免费讲座和项目实战中学到很多!这里强力推荐一下!1MHz 给了很多技术支持,欢迎大家也去参观一下他的Electron作品Knotes。xwartz 的PupaFM详细的commit记录对我学习Electron帮助很大,希望大家去也给这个项目点个赞。

本文由 华盟网 作者:小龙 发表,其版权均为 华盟网 所有,文章内容系作者个人观点,不代表 华盟网 对观点赞同或支持。如需转载,请注明文章来源。

0

发表评论

// 360自动收录 // 360自动收录