迁移业界优秀模块到 spmjs.io 并反推的简易教程

现在你发现有一个优秀的前端模块在 spmjs.io 上找不到，需要把它发布上来。

下面以 echo 为例简要介绍如何迁移业界模块到 spmjs.io 上。

一、Fork！

二话不说，首先把这个仓库 fork 到你的仓库下，比如 https://github.com/spmjs/echo 。并把这个仓库 clone 到本地，方便下一步的修改。

我们不倾向于按照 spm init 的官方模板来改造业界模块，而只需要补充必要的信息就可以了，这样可以最小程度的保持和业界模块现有的目录接口和开发方式的兼容。

spmjs.io 对模块代码的要求是必须为 CommonJS 规范。对于很多业界模块，一般的书写规范有以下几类：

CommonJS 的写法。

比如 npm 上的前端模块和 Component 上的模块，它们的代码和 spmjs 完全兼容，不需要进行修改。
类 UMD 的写法。

比如 jQuery 和 underscore。这样的写法一般都是兼容于 CommonJS 环境的，所以也不需要修改。
简单的闭包写法。

比如 essage 这样，把接口暴露到全局变量下进行使用的方式。这样就需要有一些改动，把暴露全局变量改为 module.exports = new Essage(); 这样。

通常来说，用 UMD 的方式来解决不同使用环境下的接口暴露问题会比较友好，因为这样改动可以兼容原来的使用方式。
```
// CommonJS
if (typeof exports !== 'undefined') {
  module.exports = Obj;
}
// AMD
else {(typeof define === 'function' && define.amd) {
  define(function() {
    return Obj;
  });
}
// Global
else {
  window.Obj = Obj;
}
```
经典 AMD 的写法。

指的是 define(['jquery'], function(jquery) { ... }); 这样的源码书写方式，而且原仓库没有提供构建后的使用文件。不要尝试进行修改，建议放弃。
CMD 的写法

指的是 define(function (require, exports, module) { ... }); 这样的源码书写方式。去掉 define 包裹块即可。

现在按照上面的规则审视一下 echo，可以发现它采用了 UMD 的写法，非常好，不需要任何修改。

改造完源码后，需要在 package.json 中添加 spm 的相关字段，才可以发布到 spmjs.io 上。

spm.main

入口文件，从根目录开始写起。对于 echo 来说：
```
"spm": {
  "main": "src/echo.js"
}
```
spm.dependencies

如果模块有依赖，需要添加相关的信息，你可以到 spmjs.io 查询相关的依赖模块的版本信息，或在命令行中运行 spm info xxx 进行确认。
```
"spm": {
  "dependencies": {
    "underscore": "1.6.0",
    "jquery": "1.10.1"
  }
}
```
并确保模块源码中有相关的 require('jquery') 语句。
spm.output

如果有必须的样式/图片文件，可以用 output 属性进行指定。
```
"spm": {
  "output": ["style.css"]
}
```
补充其他信息。

name 和 version 是必须的，name 必须和 spmjs.io 已有的模块名不同，version 则必须常用 x.y.z 这样的格式。

其他信息如 homepage、repository、keywords、description 对于模块的信息完整度很重要，建议保持原仓库提供的信息。如果原来没有的话，可以酌情补充。

对于现有仓库，有很多文件对于 spmjs.io 的包来说不是必须的，比如测试、演示和文档文件。我们可以通过添加这样的 .spmignore 文件进行忽略，避免发布到 spmjs.io 上的包体积太大。

$ spm publish

如果提示没权限，请先 spm login。

这样，这个包就发布到 spmjs.io 上了：http://spmjs.io/package/echo.js

最后，我们希望把这些改动回推给社区，这样下次更新时，直接从作者的主干上操作就可以了。

在自己仓库的页面上点击 Pull Request -> New pull request，进入比较页面：https://github.com/spmjs/echo/compare/toddmotto:master...master
确认改动后，点击 Create pull request。在标题里填写 Add spm support，内容可以按照 https://github.com/spmjs/spm/issues/781 里提供的模板来写。
点击右边的 Create pull request，这就成功的回推给原作者了。
下面就是等待作者的回应，按照我们之前的经历，不同的开发者对于包管理有不同的理念，可能成功，也可能失败。你可以到向开源项目推广 spm 的汇总反馈你的工作。

如果作者比较好说话，也可以酌情添加 spm badge 和 spm install xxx 的安装提示信息。
[![spm package](http://spmjs.io/badge/zen)](http://spmjs.io/package/zen)

大功告成。如果你的 Pull Request 成功了，这个模块的后续维护就变得非常简单。只需要 clone 下官方仓库，并切换到对应的 tag 上，运行 spm publish 即可！

问：不需要 spm doc publish 吗？

答：业界的模块大多有自建的文档，不需要按照 spm doc 的文档格式来发布。