《Steem指南》 -- 编辑的工作流 | Editors' Workflow

文档介绍

• 目的：

  • 帮助编辑们理解如何将作者们创作的内容合并到《Steem指南》中

  • 保证《Steem指南》全书的格式正确、内容质量高

• 角色：

  • 作者（Author）：创作和分享《Steem指南》的内容

  • 编辑（Editor）：审阅作者发布的内容，并提交到《Steem指南》的源代码

  • 项目维护者（Maintainer）：审阅编辑提交的内容，并合并到《Steem指南》在线版本

编辑审核流程

1. 审阅

2. 编辑

3. 修复

4. 发布

#1 审阅

我们目前采用每周修订一章的策略，细水长流，并减少编辑的工作量。

所以，编辑主要是对本周获得的稿件进行审阅。

1. 查看投稿：每周的修订工作开始后，编辑可以在页面 https://busy.org/created/steem-guides 查看最新给steem-guides的投稿。

2. 审阅稿件：对于每一篇投稿，编辑需要对内容进行审查，并回复相应的修改建议、或提出疑问；确保稿件的最终内容满足要求、格式符合写作规范，并确实能够使得读者受益。对于通过了审阅的文章，编辑需要回复作者审核已经通过，即将提交。

#2 编辑

对于通过审阅的作者投稿，需要把他们合并到书籍当中。我们的书籍的源代码在GitHub仓库：https://github.com/steem-guides/steemh

下面是编辑的流程：

(1) 找到对应文件：比如第二章，对应的文件就是02_0.Rmd，点击打开文件 https://github.com/steem-guides/steemh/blob/master/02_0.Rmd 我们可以看到该章节的markdown源代码。

（2）添加作者的稿件：点击右侧的编辑按钮（笔的图标），进入到编辑页面：https://github.com/steem-guides/steemh/edit/master/02_0.Rmd

用steemd查看稿件的markdown源码，比如https://steemd.com/github/@evathinking/github（将页面连接中的steemit.com替换成steemd.com，即 it -> d）。注意：这里只是做例子，并非真的要编辑此文。

将steemd中的markdown源码，复制到GitHub中对应的章节。

需要注意的是，有一些地方需要做一些替换：

1. @字符在RMarkdown（.Rmd）文件中需要用\@来表示（@前加反斜杠）；

2. 图片需要上传到images文件夹中。（建议等Pull Request创建以后再添加新的图片，下文会提到）

（3）对比修改：点击顶部的Preview changes按钮，可以和前一个版本对比修改的文本，可以看到新增或删除的文字，查看格式是否正确。

（4）提交Pull Request：修改和预览完成后，可以滚动到页面的最底部，提交一个Commit（一次贡献），添加本次提交的基本说明（如修订第2章），然后选择Create a new branch，在下面的branch名称中输入（章节+日期，如chapter2-2019-0401）。点击Commit changes按钮。

随后会进入到Pull Request的页面，比如https://github.com/steem-guides/steemh/compare/master...chapter2-2019-0401?quick_pull=1。一般不需要修改，点击“Create pull request”创建Pull Request

随后一个Pull Request就会被创建了：https://github.com/steem-guides/steemh/pull/5

至此，一个Pull Request创建成功了，如果Pull Request被Merge（合并）到master branch中，书籍就会被自动编译和发布。

#3 修复

Pull Request创建成功以后，编辑的大部分工作都已经完成了，但还有几项工作需要关注：

(1) 查看书籍编译结果：查看新提交的源码的自动编译的结果，是否出现错误。如果出错就没法合并了，如下图所示：

我们点击Details链接，可以看到编译失败的原因：https://travis-ci.org/steem-guides/steemh/builds/514183601?utm_source=github_status&utm_medium=notification

可以看到出错原因是图片没有存到本地：

(2) 继续修改：如果有图片要上传或者其他文本要修改，我们也可以在这个阶段进行；

比如上面的错误告诉我们图片没有上传，我们继续上传图片。

点击标题下方的branch的名称（此处是chapter2-2019-0401），进入到branch的页面：https://github.com/steem-guides/steemh/tree/chapter2-2019-0401

然后点击images文件夹，进入文件夹的页面：

将刚才没有上传的图片文件从steemit下载，并且按照“章节-内容-编号”的格式命名，比如：

点击Upload files按钮，在页面中上传上面的图片

上传成功后，添加注释（如第2章修订：上传图片），说明修改的内容。选择commit directly to the XXXX branch，点击Commit changes按钮。

完成后会回到branch的页面，继续选择章节的RMarkdown文件（.Rmd），如02_0.Rmd。

编辑02_0.Rmd文件（编辑方法同上面提到过的一样），修改图片的链接，为刚才上传的文件的相对路径，如下图所示：

点击Commit changes按钮，再次提交02_0.Rmd文件。

修改提交完毕，点击<>Code这个标签，回到文件夹的首页。

然后点击上面的View #5（或其他数字）链接，可以回到我们之前创建的Pull Request:

接下来，我们需要等待编译和部署的任务自动完成（大约5分钟）。如果编译成功（绿色），我们则进入到下一步；否则，我们需要继续修改RMarkdown文件，修复潜在的问题。

(3) 审查在线书籍：提交完成后，如果没有格式等问题，编译和预发布会成功，我们需要继续做一些审查。

编译成功时，在Pull Request的页面会显示绿色的勾：

这时，我们可以打开预发布的书籍链接（不是正式发布的地址）： https://steem-guides.github.io/steemh-staging

并查看最新编辑的书籍内容是否可以看到了，以及pdf/epub等格式是否可以提供下载了：

由此我们可以看到，我们在上面添加的内容已经成功部署了，但存在几个问题：

1. 2.14.1小节的内容不应该从属于2.14。实际上，它也不应该是第2章的内容，我们应该把它放到正确的章节。并且，如果是放在第2章，它也应该和2.14小节处于同一层级；我们应该选择正确的heading（标题），应该是##（第二级）而不是###（第三级）

2. 图片的下方显示了图片的文本，但没有意义，我们应该在编辑RMarkdown时输入合适的图片说明，或者不提供说明。即 中，1.png应该换成更有意义的文字，或者删除。

如果要继续修改，我们可以返回上一步的过程继续修改。如果基本满意，那么编辑的工作就到此大功告成了，恭喜！:)

#4 发布

最后一步，将最新的改动发布到《Steem指南》的在线版本：https://steem-guides.github.io/steemh/

编辑在工作完成后，通知GitHub项目的维护者（Maintainer）已经提交了Pull Request并预发布成功。维护者检查编译和预发布没有问题后，将点击Merge pull request按钮，将当前的Pull Request的代码合并到master branch（主分支）。

合并完成后，对于最新版本书籍的编译和发布将自动触发，将书籍发布到https://steem-guides.github.io/steemh/，并提供pdf和epub的下载。

恭喜所有参与者，至此创作、编辑和合并的工作已经完成了！

不知道你学会了没有？可以根据上面的步骤实验一下哦。

最后

本文适用于《Steem指南》的编辑阅读，也方便其他读者了解《Steem指南》的编写工作是如何完成的。

技术性说明：这里我们没有采用常见的fork模式进行代码贡献，所以需要编辑拥有对于https://github.com/steem-guides/steemh 代码仓库的写权限（加入editors团队）。由于editors没有对于master branch的写权限，必须通过pull request来提交编辑后的成果。

对《Steem指南》编辑的工作流程，如果有更多疑问，请咨询@steem-guides或者@robertyan。