前段时间翻译的Spring MVC官方文档完成了第一稿，相干的文章和堆栈可以点击以下链接。这篇文章，主如果总结一下这个翻译项目自最先到上线宣布，完全的一个性命流程。内容包含 翻译环境搭建 、项目治理 与 自动化构建 三部份。
环境搭建
翻译与写作一样，重要之事均为专注于翻译/写作自身，而不斟酌款式等方面。而章节之间的联络，天然也不想过量费心，这部份与款式一同，都可交由东西去处置惩罚。然后版本治理，不用说肯定要上，背面也会看到github的生态圈使得它与其他东西做到了无缝集成。那末总结起来，我们须要的东西大致是：
markdown
markdown编辑器 Atom
版本治理 Git
代码托管平台 Github
写书专用东西 Gitbook
HTML转markdown东西
Markdown
Markdown是一种近乎圆满的写作标记言语，其最大的劳绩就是将写作从内容中星散出来，这个星散使你只专注于写作内容自身，极大地进步了效力及事情愉悦度。没有markdown的话，会是怎样一种状况？想一想HTML和写论文常常运用的word。你在HTML中为内容混入林林总总的款式，写论文时最痛楚的莫过于调款式（不过笔者昔时写论文时经由历程Office Word的款式窗也是圆满地处理了内容和花样的题目）。
比方说，上面这段笔墨在markdown中写出来是如许的：
## 环境搭建
翻译与写作一样，重要之事均为专注于翻译/写作自身，而不斟酌款式等方面。而章节之间的联络，天然也不想过量费心，这部份与款式一同，都可交由东西去处置惩罚。然后版本治理，不用说肯定要上，背面也会看到github的生态圈使得它与其他东西做到了无缝集成。那末总结起来，我们须要的东西大致是：
* markdown
* markdown编辑器 Atom
* 版本治理 Git
* 代码托管平台 Github
* 写书专用东西 Gitbook
* HTML转markdown东西提及来markdown这个名字也有点意义，平常的标记言语叫markup language。这里将up改成down，寄意着将标记言语中与内容自身无关的标记悉数剔除，构成一个精简子集。本篇不是markdown用法记，所以更多的语法请自行百度Google。我这里可以供应几个链接：
Markdown编辑器 Atom
编辑器的遴选并没有定式，打造一个完全符合本身操纵习气的编辑器也是每一个程序员应做的一个事情，这里我不赘述。在Mac上，不错的markdown编辑器有Sublime 3、Atom、MacDown、Mark Editor、Gitbook Editor、Mou等，可遴选合适本身的，我遴选的是Atom，是由于有一个刚性的需求它可以满足：
与终端（terminal）的集成。由于运用了版本治理，同时偶然有拷贝文件、检察目次等需求，敕令行肯定是必需随时在手的。终端方面我的遴选是iTerm2+zsh，关于它们的设置和特征，可以检察博客的这两篇文章 Mac文雅的东西集——iTerm2篇 和 Mac文雅的东西集——oh-my-zsh篇。对如安在Mac上构建一个文雅的东西集有兴致的同砚，也可之前去Gitbook看看我正在写的这个系列：关于文雅地运用Mac OS的理念、主意、东西与实践集，不过还没写完就是了。
版本治理 Git
Git作为版本治理的意义也不赘言。你肯定不想本身的事情区末了变成如许：
同样本小节也不是Git入门的敕令集，这部份请自行查阅进修。固然我照样可以给出一些链接，虽然没有太多的意义我真的不知道为何我还要给。基础的几个敕令能熟习便可以满足一样平常的须要了。别的，zsh下的Git可以配一下 快捷键(alias) 和 自动补全，详细设置异常简朴，可以来这篇文章Mac文雅的东西集——oh-my-zsh篇看一下终究的结果。
代码托管平台 Github
Github是世界上最大的同性结交平台现在最大我并没有根据的代码托管平台，其生态圈之繁华与气力令人震惊，险些你须要的统统东西和资本都可以在上面找到。它与Git不是一个层级的观点git=github.substring(0, 3)，这部份请自行搜刮。在这个平台上，我可以给翻译项目一个README.md文件，为浏览的人做简朴的引见以及引流，同时它可与CI（延续集成）、Gitbook等东西圆满集成，其内置的issue、pull-request功用还能与Zenhub连系，直接当做trello来举行项目治理之用。相干的东西下一节会引见。
写书专用东西 Gitbook
上文提到了翻译内容与款式的星散。实际上在这里款式这部份就是由Gitbook自带的衬着引擎来担任的。另外，Gitbook还能协助你治理全部书的目次构造、章节天生、搜刮、词汇表、站点构建与天生等，同时它也有雄厚的插件生态。这统统只须要你举行少许的设置（实在，就只是在书的根目次下运转gitbook init敕令，它会天生下图所示的一个目次构造），其低进修本钱与高效益，使它成为了写书最易入门的趁手东西。
.
├── README.md
└── SUMMARY.md项目治理
项目治理方面的需求，主如果偶然会有主意涌现，愿望增添什么特征，或许想到什么题目不想立时修，那末最好是有一个TODOLIST可以随时记录下来，并且能被方便地检索到。这方面的需求，怎样处理呢？
issue + zenhub
Github内置的issue功用已好用到爆，再加上专为Github issue功用定制的Zenhub几乎就是活生生把issue当做trello来用。一些内置特征以下，略加体验即可满足统统小型项目治理上的需求：
issue可以经由历程commit sha直接与相干的单次提交关联，还可以 经由历程提交信息来援用、封闭issue
issue中支撑GFM(Github Flavored Markdown)，可以直接运用todolist的语法
经由历程Command/Ctrl+V可以直接在留言中上传截图
可认为issue增加标签（tag）、种别（pipeline, 如正在做、还没做、已完成等）
可认为issue估点、指定担任人、燃尽图，几乎就是为迅速实践而生，不过在这个翻译项目顶用不到这些，毕竟本身给本身估点没什么意义
自动化构建
自动化什么的构建？这还要从本翻译稿的托管平台——Gitbook——提及。gitbook是一个绝好的写作平台，官方也经由历程Webhooks供应了与Github的集成，只需你把代码git push到远端堆栈，Gitbook就会自动拉取堆栈中的内容，遵照特定的花样为书籍构建站点。过也许2到3分钟，你便可以在Gitbook上看到本身最新的更新已到书上了。统统看起来都非常优美，一键提交与布置。然则有一个最大的题目：Gitbook在国内的速率不可，轻则卡顿，重则整站被墙刷不出页面。
这类状况下，我决议将全部翻译同时迁徙到七牛上。七牛的CDN在国内速率名声在外，用来托管静态站点再好不过只须要拍两张身份证正反双面的照片上传守候考核即可。迁徙也很简朴，由于gitbook天生的静态站点实在就是_book文件夹，只须要把这个文件夹下的悉数东西放到七牛空间上去，在运用index.html作为进口便可以了。然则，题目又来了：
七牛网站上没法上传文件夹。就算可以，我也没法忍耐每次都要手动将文件夹拖上去
每次堆栈有更新，都须要将最新的内容同步到七牛空间上，并掩盖旧版本的同名文件
第二步的操纵还不能经由历程githook+shell的体式格局来做，由于全部历程的耗时会使
git push的反应周期变长，从而使得我更不倾向于频仍提交，影响翻译体验
处理方案也很简朴：
第一条，寻觅七牛的SDK，经由历程敕令行举行上传
第二条，既然不能，[细想]也没必要在当地做，那末就在远端做好了。远端在那里呢？CI/Pipeline啊，如许构建站点、同步文件等事情都可以并行举行了，既不会障碍当地开辟速率，也不是翻译时须要斟酌的题目，我照样只须要像之前一样
git push提交代码即可，站点从构建到终究上线，都有CI在担任
主意出来了，在实行的时刻照样走了一些弯路的。这些折腾历程在此没法深表，只要能够带历程序员们都懂的。在CI的遴选上，我遴选了Jenkins 2.0，缘由比较地道，近来项目上在运用Jenkins 2.0，我恰好当是练手。至此文章成笔之时，我仍在考核其他遴选，比方travis-ci，看起来UI和设置都简朴很多，这部份多是后文了。下面会简朴引见折腾搭建Jenkins 2.0作为本翻译项目CI的步骤和症结节点。
Jenkins下载、装置与启动
话说Jenkins不愧为CI/CD范畴的前锋，这个产物每周都会发一个小版本（现在最新是2.11）。Jenkins 2.0的装置，可以经由历程直接下载装置包的体式格局下载，在Mac上也可以经由历程brew install jenkins来下载装置。装置完成后，运转jenkins即可在localhost:8080启动一个当地的jenkins。
注册一个七牛开辟者账号
流程非常简朴，免费用户可以有一个空间，有肯定的流量限定，不过一般来讲关于只要一个空间需求的用户来讲，如许的流量应当不会超吧。由于我已超过了一个空间的需求，同时我又有设置自力域名的需求，所以须要更多的权限。流程也很简朴，举行实名认证、填写身份证、上传本人及身份证正背面照片各一张本人不需拍背面，末了保证账户里有起码10元即可。
Jenkins：新建一个范例为pipeline的项目
pipeline搭建起来了，接下来我们须要捋一捋前面说到的两个步骤：构建站点、上传站点文件到七牛空间。细分下来，主如果有以下的task要做：
引入必要的依靠
构建站点
同步到七牛
运用NPM，引入gitbook/gitbook-cli/qiniu
我们想要构建站点，必定运用gitbook的敕令行东西；要运用七牛的敕令行，也必定引入响应的东西。这里我走过一些弯路，比方尝试将七牛东西以插件情势引入到Jenkins job中来，然则2.0今后，我们更倾向于运用脚原本形貌构建事情，而非将Jenkins纯真看成一个转存/转储的事情区间并为该workspace零星地写一些适配剧本。因而，在pipeline范例的项目就不存在每一个job特定的设置空间，若想运用插件，设置起来有些贫苦。因而，末了我决议运用七牛的npm包（肯定是有的），并经由历程NPM来治理统统依靠。以下是一个package.json文件需引入的依靠：
{
...
"devDependencies": {
"gitbook": "^3.1.1",
"gitbook-cli": "^2.3.0",
"qiniu": "^6.1.11"
},
...
}别的，须要注重的是，Gitbook的衬着引擎已升级到v3.1.1版本，与Legacy v2.6.7版引擎比拟，重要的区别是v3支撑多个部份(part)的文章、默许封闭了目次中章节前的数字等。个中multipart的部份有些小bug但还可以忍耐，然则默许封闭的目次数字则须要经由历程以下的设置给设置返来。在book.json文件中：
{
"gitbook": ">=3.1.0",
"pluginsConfig": {
"theme-default": {
"showLevel": true
}
}
}构建站点
简朴地运转敕令gitbook build即可天生站点目次。末了的构建剧本Jenkinsfile.groovy以下所示：
node ('main') {
stage 'Pull latest changes from SCM'
git([
url: 'git@github.com:linesh-simplicity/translation-spring-mvc-4-documentation.git',
branch: 'master'
])
stage 'Download dependencies: Gitbook/Gitbook-cli/Qiniu'
sh 'npm install'
stage 'Build book serving directory through Gitbook'
sh 'gitbook build --gitbook=3.1.1'
stage 'Upload production _book to Qiniu through their API'
sh './jenkins/sync-book-to-qiniu.sh'
}上传文件到七牛
运用七牛的敕令行东西举行文件上传，须要设置一些东西，主如果要同步的当地目次、七牛的Access key和Secret Key等，示例代码则可以从七牛SDK的官网上参考。我末了完成的这份同步剧本sync-book-to-qiniu.js以下所示，个中完成了 预备当地同步目次 、 消除不同步文件 、 指定掩盖上传战略等事情：
const qiniu = require("qiniu");
const glob = require('glob');
const crypto = require('crypto-js')
const ignoredFiles = [
'Jenkinsfile.groovy',
'sync-book-to-qiniu.js',
'sync-book-to-qiniu.sh',
'mvc-origin.md',
'package.json'
];
// node ./jenkins/sync-book-to-qiniu.js $ACCESS_KEY $SECRET_KEY
let qiniuAccessKey = process.argv.slice(2, 3);
let qiniuSecretKey = process.argv.slice(3);
// Prepare Qiniu configuration options
qiniu.conf.ACCESS_KEY = qiniuAccessKey.toString(crypto.enc.Utf8);
qiniu.conf.SECRET_KEY = qiniuSecretKey.toString(crypto.enc.Utf8);
bucket = 'mvc-linesh-tw';
glob.sync('_book/**/*.*', {}).filter(filename => {
for (let ignored of ignoredFiles) {
if (filename.endsWith(ignored)) return false;
}
return true;
}).forEach(filepath => {
const resource_key_in_qiniu_api = filepath.substring('_book/'.length, filepath.length);
// ':' means allow override upload. For further details refer to offical API docs
const policyToken = new qiniu.rs.PutPolicy(bucket + ":" + resource_key_in_qiniu_api).token();
uploadFile(policyToken, resource_key_in_qiniu_api, filepath)
})
function uploadFile(uptoken, key, localFile) {
let extra = new qiniu.io.PutExtra();
qiniu.io.putFile(uptoken, key, localFile, extra, function(error, response) {
if(!error) {
console.log('[Success] File uploaded: ' + response.key);
} else {
console.log(error);
}
});
}偕行们求review代码啊～
防止提交七牛的AK和SK
AK(Access Key)和SK(Secret Key)是七牛分配给注册开辟者的一对密钥，不能泄漏，不然其他人得到了便可以对你的七牛空间举行恣意操纵。然则，你要把构建事情自动化，就必需这段剧本提交到github上，同时CI还要能从你的代码中读出准确的AK和SK，这要怎样做到呢？回复是，经由历程CI供应的接口，由pipeline将参数注入到你的代码中。如许，AK和SK就被保存在了pipeline上，他人无权对其举行接见。在Jenkins CI上，这是经由历程一个EnvInject插件来做到的，在travis-ci中则越发简朴，直接设置。
总结
呼呼，末了看到这个图的时刻照样很冲动的，统统的布置事情都胜利了。那末也是时刻完毕了，本篇文章总结起来，先是提到怎样预备和搭建让翻译事情越发专注和高效的环境和东西，如markdown/atom/gitbook/git/github等，然后讲到怎样运用github的issue和zenhub来辅佐治理翻译项目中的待办事项和合作，末了一节报告了怎样运用CI东西将全部站点的构建和宣布自动化，进步翻译和布置效力。任何有疑问或说错的处所，也请列位给我指出。
—— 2016-07-01
