Wix

由于本文内容较多，先列一下目录供参考。

什么是开源？
为何做开源？
做什么？
注册账号
搭建开发环境
提交代码
创建官网
如何宣传？
持续迭代
总结

什么是开源？

您可能有很多次打开 github 去查阅下载一些项目的源码，但是您有没有总结过，开源项目到底是什么？

# 我与开源

我是开源编辑器 wangEditor (opens new window) 的作者（欢迎去 star），这个项目已经做了有近 4 年了，目前积累了 4.5k star（现在是 2018.5）。4 年时间，我一直未间断维护升级，其中还经历了 2 次大型的重构，积累了一些经验和教训。接下来我将根据自己的经历，来为大家分析开源。

# 开源项目包含什么

开源软件并不是只是一堆源代码，如果你仔细分析或者有亲身体会的话，包含内容还是比较多的。我总结了以下内容：

源码
文档，如二次开发文档和用户使用文档
开发环境，告诉二次开发者如何搭建和运行代码
允许他人贡献代码，而不是仅仅给别人阅读源码的权限
问题，用户提问，维护者答复，问题共享（而不是私聊）
问题列表和升级计划，记录当前问题，以及何时解决、何时升级

# 其他配套设施

要做成一个成熟靠谱的开源软件产品，除了以上源码相关的方面，还需要以下配套的设施，才能完备。

官网，如 wangEditor 官网 (opens new window)
文档，可以和官网整合在一起
问答社区，wangEditor 的问题社区就用了 github issue (opens new window)
及时交流社区，即 QQ 群、微信群

为何做开源？

做开源不挣钱，这是确定的，但是为何要做开源，而且那么多人坚持做开源呢 —— 他们不是完全为了兴趣爱好，完全下班没事儿干。人只要付出劳动、付出努力，都是奔着目的性去的，有兴趣的原因，但是能让自己持之以恒做下去的，肯定不是兴趣。

其实这个问题很简单，就像看书不挣钱（买书还花钱呢），但是为何要看书呢？因为大家都知道看书能提高自己的知识面和能力。而做开源也有相似的想过，只不过很多人没接触过不知道而已。我总结了如下几个理由：

全面提高编程能力。你需要从 0 打造，每部分代码都需要自己负责，不像在公司中的一颗螺丝钉。
提高自己的社区知名度。 github 上的 star 能间接的反应你的身价，它能让你得到业内认可。业内同行认可了，做啥事儿都好做，如内推工作。
锻炼自己的产品意识。因为做开源做的是产品，不再是单纯的技术活，UI、运维、推广、收集反馈、甚至成本预算，你都得考虑。
技术范儿、极客精神。作为一名程序猿，能业余打造一款开源产品是一件很帅的事情，满足自己的虚荣心。

有了充分的理由，那就开干！

做什么？

# 迈出第一步

这是做开源要想到的第一件事情，很多想做开源的同学，到这一步就想不下去了。还有同学，一上来就定位太高，做着做着发现根本做不出来，就提前放弃。做什么，看似简单的问题，但是很重要的一步。

# 不做什么

一些早期就知名的开源作品，很多都是因为作者在工作中遇到一个需求，而这个需求目前还没有开源产品去满足，因此自己做一个。但是对于我们大众基层程序猿，天天写业务代码，重复劳动，你遇到这种需求的概率不是特别大。因此，这个方面就不在继续往下讨论了。

想要知道做什么，你就得先明白你做开源的一些期望，然后再去想做什么。我总结了两点：

要快速做出第一版，至少能用。后面再慢慢迭代升级。
要能方便的推广使用，最好是 0 成本使用。

即做出来，推出去，要快。即，你做的快，别人用的也快。按照这种期望往下想，首先你能排除不做什么：

大型的框架，如做一个 UI 框架。短期做不完，使用成本高
模拟成熟轮子，如在造一个 jQuery 。有成熟方案，用户不会换
小众的东西。基本没人用
没有特色，100% 的模仿。用户没有更换的理由

# 做什么

排除以上这些，还剩下的范围就不做了，我推荐做开源产品的方向：

小而精的工具。开发快，使用成本低。
要有特色，哪怕是一个。要和别人不一样，差异化竞争。
一定要大众，50% 以上的开发人员都会用到
避开已经被成熟产品垄断的领域。你就不要去跟 jQuery vue React 竞争了。

例如，前几天 is-odd (opens new window) 在知乎闹的沸沸扬扬，这个库就是判断奇数偶数，只不过考虑了各种数据类型的转换。但是你看它的 weekly downloads 数量多大。

下面列举几个我认为比较合适做开源的例子：

cache 工具（缓存工具，整合 localStorage，以及合理的内存销毁机制）
query2json，解析 url 参数为 json 格式
移动端打印 console.log ，方便移动端输出内容

其他符合上述条件的，根据自己当前的情况，大家可以自由发挥。最后，选择哪个不重要，重要的是你选择出来了。因此，如果你实在没有合适的选择，不如就从我举例中选择一个，抓阄也行。选择出来，你就可以继续往下做了，否则你一直都在纠结。

# 本文将做什么

好了，本教程就确定要做一个 cache 工具，取一个性的名字，不和现有的重复（是否重复，去 github 一搜便知），叫做fast-cache。

注册账号

注意，你如果现在已经有了 github 账号，也不好忽略这一章的内容，很重要！

你一旦注册一个 github 账号并且去做开源产品，那你就要作为一个个人品牌持续运营下去，不能随便改名字。因此注册账号时一定要慎重考虑，不能随便弄一个，做一段时间又想改。

# 组织还是项目

首先，你要明确你即将注册的账号是专门针对一个产品（即项目账号）还是将运维多个产品（即组织账号）？

例如，facebook (opens new window) 就是 github 中的组织账号，其下有很多开源产品，如 react (opens new window) 和 hhvm (opens new window) 等。而 rollup (opens new window) 就是 github 中的项目账号，其下就一个项目 rollup (opens new window) ，其他的项目都是一些附件插件。

对于我们个人开发者，我推荐注册项目账号，即以你项目的名称取个账号的名字。这样还有一个好处，就是后面讲到官网的时候，你可以用更短、更好记的官网地址。例如，如果不自己申请域名、假设服务器（即不花一分钱）的情况下，以上例子中他们的官网有区别。

rollup 的官网地址将是 rollup.github.io ，很短；
react 的官网地址只能是 facebook.github.io/react，多了一级目录；（注意是不申请域名、不花钱的情况下）

最后，我选择项目账号，因此我需要注册的账号是 fast-cache 。

# 注册账号

我们分别要去 github (opens new window) 和 npm (opens new window) 注册以 fast-cache 为用户名的账号，注册过程就不写了，都是傻瓜式操作。需要注意的是，如果被墙，自己想法办科学上网。

# 创建项目

图片描述

创建完成之后，通过 https://github.com/fast-cache/fast-cache 即可访问到项目的主页，这是你就已经有了自己的开源项目了。

# 添加 `ssh key`

ssh key 就是连接你的电脑和 github 服务器的一把钥匙，只有添加成功了才能把你本地的代码提交到 github 服务器。

如果你是 mac os 系统，运行 ssh-keygen 即可一步一步生成 ssh key ，然后运行 pbcopy < ~/.ssh/id_rsa.pub 即可拷贝下来，等着粘贴。windows 系统用户，自己百度搜索 github ssh key 即可找到相关介绍文章，跟着做就行了。

在 github 个人中心的设置界面，能找到 SSH and GPS keys 菜单栏，或者直接访问 https://github.com/settings/keys 。页面中点击右侧“new ssh key”按钮即可添加 ssh key ，把刚才的内容粘贴过来添加上就行了。

# 下载代码

进入 github 项目主页，复制 git 地址（注意选择 use ssh ，不要 use https ），如下图

图片描述

复制下来的内容应该是 git@github.com:fast-cache/fast-cache.git ，然后你选择一个合适的文件夹或目录，执行下载命令。

git clone git@github.com:fast-cache/fast-cache.git

下载完毕，进入代码目录，运行如下命令修改当前 git 的用户名和邮箱，改成和当前 github 用户名和注册邮箱一致。

cd fast-cache
git config user.name 'fast-cache'
git config user.email 'fast-cache@github.com'

最后，随便修改一下 README.md 文件的内容，然后提交，看能否成功？成功了就说明刚才的ssh key 生效了。

git add .
git commit -m "first update"
git push origin master

搭建开发环境

# 初始化

进入项目目录，然后命令行运行 npm init ，按照提示进行初始化即可。提示中的信息，能写的都写上，别随意忽略了。初始化完成之后，项目根目录下会有 package.json 的文件。

# 规范版本号

打开 package.json 文件，将版本号定义为 "version": "0.0.1" 。以后我们每次正式提交代码，版本号都不一样。版本号分三级，分别为：

一级，重构版本
二级，重大功能改进
三级，小升级或者 bug 修复

为何从 0.0.1 开始？因为 0.x.x 可以认为是非正式版本、测试版，而从 1.x.x 开始，就是正式发布的版本了。

# 规范一级目录

项目的一级目录要提前规范好，最起码一些常用的目录要提前订好留用，不能乱来。例如：

src - 源代码
release - 发布结果
test - 单元测试用例
doc - 文档
example - 示例

build 构建脚本 dist 编译出来的发布版 docs 文档 examples 示例文件 src 源码 test 测试脚本 .babelrc Babel 交叉编译的配置 .eslintrc ESLint 测试配置 .gitignore 哪些文件不要上传到 GitHub .gitattributes 文件属性，如 EOL、是否为二进制等 LICENSE 授权协议 README.md 自述文件，里面至少得写：项目的特色各种 Badge 比如 CI 的怎么下载安装示例运行/使用怎么编译（尤其 C/C++，要把编译器、要装什么工具、依赖库全部写清楚。要带版本号！）怎么参与 circle.yml Circle CI 持续集成配置文件（当然你可能用别的 CI，名字会变。比如我那个 otfcc 使用了两个 CI：Travis 和 Appveyor，就写了两个配置） bower.json Bower 包管理器配置文件 package.json npm 包管理器配置文件

# 构建工具

这部分比较独立，内容也比较多，就不详细讲了，用最常用的 webpack 做一个简单演示吧。

安装插件 npm i babel-core babel-loader babel-polyfill babel-preset-es2015 babel-preset-latest webpack webpack-cli --save-dev 。

项目根目录下创建 .babelrc 文件，内容如

{
    "presets": ["es2015", "latest"],
    "plugins": []
}

项目根目录下创建 webpack.config.js 文件，内容如

module.exports = {
    entry: './src/index.js',
    output: {
        path: __dirname,
        filename: './release/bundle.js'
    },
    module: {
        rules: [{
            test: /\.js?$/,
            exclude: /(node_modules)/,
            loader: 'babel-loader'
        }]
    }
}

最后，修改 package.json 中的 scripts ，增加 "release": "webpack" 。然后命令行运行 npm run release ，就可生成 release 的内容。

# 运行示例

release 的内容已经发布出来了，还要运行起来，最简单的方式，在example创建test.html，然后引用 release 的内容。

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>example</title>
</head>
<body>
    <p>example</p>
    <script src="../release/bundle.js"></script>
</body>
</html>

为何规范化运行，可以修改 package.json 中的 scripts ，增加 "example": "http-server -p 8880" 。然后命令行运行 npm run example ，浏览器访问 http://localhost:8880/example/test.html 。

# 规范 git 分支

至少要存在两个分支，master 和 dev ， dev 是开发中的代码。当然，你可以规范更多的分支，例如 next fix-bug 等，但是注意一个原则 —— 用不到的就先不要规划。

# 完善 `README.md`

README.md 是开源项目的一张脸，用户的第一印象。必须包含以下内容：

产品简介（此处要突出特点，打差异化竞争）
产品安装和下载
快速使用（详细的使用文档或者二次开发文档，外链即可）
交流提问区
关于作者（放你的博客链接，和收款二维码）

最后，把以上完成的工作，都提交到 github 中。

提交代码

# 写代码

具体写什么代码不是本文的重点，你尽情的根据自己的项目来写自己的代码就是了。记得一定要使用编码规范的工具，例如 es-lint 等，否则经过长时间的维护，必然留坑。

# 写文档 & 写测试用例

注意，文档和测试用例对于一个开源产品来说非常重要！非常重要！非常重要！而且，文档和测试用例本身就是代码不可分割的一部分。

如何写测试用例，需要用到其他工具，内容也相对独立，这里就不介绍了，自己去查一查吧。再次强调，测试用例很重要！！！

在写文档之前，还需要准备其他的工具。定位到项目目录下，npm i gitbook-cli -g 安装 gitbook ，然后创建 SUMMARY.md ，内容如下：

# Summary

* [项目介绍](README.md)
* [使用文档](doc/use/README.md)
    * [使用1](doc/use/use1.md)
    * [使用2](doc/use/use2.md)
* [二次开发](doc/dev/README.md)
    * [开发1](doc/dev/dev1.md)
    * [开发2](doc/dev/dev2.md)

其实一看这个文件内容就知道，这是一个文档的目录，你可以根据自己项目的需要重新定义这个目录。需要注意的是，第一行 * [项目介绍](README.md) 对应的是已经存在的 README.md 文件。

运行 gitbook init ，会看到各个文件都被创建了，就可以完善各个文档的内容。内容完成之后，运行 gitbook build 可以将 md 文件发布为 html 文件，默认放在 _book 文件夹。启动了 npm run example 之后，可以访问 http://127.0.0.1:8880/_book/ 查看效果。

最后，再次修改一下 README.md ，把文档的链接加上

[如何使用](./doc/use/README.md) [二次开发](./doc/dev/README.md)

# 提交第一版代码

首先，修改一下 .gitignore 文件，加上一行 _book ，把打包出来的文件忽略掉。然后用之前的方式提交到 github 的 master 分支，这里不再赘述了。

接下来，创建 tag 并提交，代码如下：

git tag -a 'v0.0.1' -m 'first commit'
git push origin v0.0.1

提交之后，下载地址就有了， https://github.com/fast-cache/fast-cache/releases 这里可以下载到各个版本的源码。

最后要提交到 npm 上，能让使用者通过 npm 进行安装。首先，运行 npm add user 和 npm login 来登录，根据提示将你之前注册 npm 时的账号、密码、邮箱写上就行了，问题不大。然后，在项目的根目录运行 npm publish . ，此时问题来了！！！

运行之后报了 403 错误，刚才明明登录成功了，不可能有权限问题呀。后来一查才知道，**原来 fast-cache 在 npm 中和其他项目重名了！！！**没办法，只能改名，将 package.json 中的名称改为 fast-cache-npm ，然后再发布就成功了。

发布之后，通过 https://www.npmjs.com/package/fast-cache-npm 就可以访问 npm 项目主页了。

注意，为项目取名时，一定要提前把名字在 github 和 npm 搜索一下，确认没有重名才行！！！

# 升级代码并提交

上述是第一次提交代码的流程，下面简述一下升级代码之后的提交流程。在代码开发阶段的步骤总结如下：

来一个 dev 分支，不要在 master 分支开发
修改 package.json 版本号，按照之前既定的版本规则修改，不能乱改
修改代码、文档和测试用例
自测
将 dev 分支提交到远程

代码开发完成之后，提交的流程如下：

再次确认版本号，因为版本号非常重要
将 dev 合并到 master ，并提交 master 到远程
创建 tag 并提交到远程
提交到 npm

# 合并 pr

pr 即 Pull Request 的简称。

开源软件最大的特色就是允许全世界的开发者都能为其贡献代码，你这个开源项目也不例外。其他人很有可能会通过 github 的 pr 为你的项目贡献自己的代码，到时候你既得欣然接受，又不能茫然接受。

其他人贡献的 pr 可以通过 https://github.com/fast-cache/fast-cache/pulls 链接看到。对于每一个 pr ，如果你想合并，直接 merge 就好了（合并完之后，本地代码要随时更新一下）；如果你不想合并，留言说明然后关闭掉即可。

创建官网

我们通过 github pages (opens new window) 的机制即可免费创建项目的挂网，不用花一分钱。

# 创建项目

登录 github ，创建一个名为 fast-cache.github.io 的项目，名字必须是这一个！！！然后下载到本地，即 git clone xxxx 。然后，进入项目目录，新建一个 index.html ，然后随便写点什么，例如 hello world ，提交到 github 远程。

最后，访问 fast-cache.github.io ，你就能看到刚才的内容了，最简单的官网就这么出来了。做到这里，你应该知道 github pages 就是一个静态页面的服务器，上传相应的 html 就能显示。

# 生成官网

此前用 gitbook 将文档生成为 html 了，应该还记得。那么我们现在重新运行 gitbook build 生成 html ，然后将所有的 html 拷贝到这里来，全部提交上去，正式的官网也就出来了。

图片描述

# 更新 `README.md`

记得要修改 README.md ，把官网的地址加进去。

引自：思否作者：双越链接：http://www.imooc.com/article/28240 来源：慕课网本文原创发布于慕课网，转载请注明出处，谢谢合作

# 我与开源

# 开源项目包含什么

# 其他配套设施

# 迈出第一步

# 不做什么

# 做什么

# 本文将做什么

# 组织还是项目

# 注册账号

# 创建项目

# 添加 ssh key

# 下载代码

# 初始化

# 规范版本号

# 规范一级目录

# 构建工具

# 运行示例

# 规范 git 分支

# 完善 README.md

# 写代码

# 写文档 & 写测试用例

# 提交第一版代码

# 升级代码并提交

# 合并 pr

# 创建项目

# 生成官网

# 更新 README.md

# 添加 `ssh key`

# 完善 `README.md`

# 更新 `README.md`