オンラインドキュメントへCI・CDを適用している話 / apply CICD methods to online documents

2018/1/24の社内勉強会で講演した資料です。

ドキュメントに対して、継続的インテグレーション・継続的デプロイを適用する話をまとめています。

Transcript

1. Copyright © NTT Communications Corporation. All rights reserved. オンラインドキュメントへCI/CD を適用している話 NTTコミュニケーションズ / @iwashi86 2018.1.24 Cloud Academy
2. ・岩瀬 義昌 / @iwashi86 ・SkyWayの中の人 ・技術面 　・WebRTC 　・自動化 (CI/CD, IaC) https://webrtc.ecl.ntt.com/
3. ドキュメントにCI/CDを 適用するメリット・やり方 について知ること (今後の業務の参考に) 本セッションのゴール
4. 前提のおさらい
5. 継続的インテグレーションとは (CI: Continuous Integration) ・ソフトウェアやシステムが正しく動作するか 　継続的に確認しながら開発を進める手法 ・コンパイル・テスト・ビルドなどの一連の流れを 　短期間で＆継続的に結合
6. 開発マシン GitHub ①機能を追加した 新コードをPush 継続的インテグレーションの例
7. CI 開発マシン GitHub ②単体/機能 テストを起動 ①機能を追加した 新コードをPush 継続的インテグレーションの例 e.g. オンプレ: Jenkins/Concourse CI/Drone SaaS: Circle CI/Travis CI
8. CI 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②単体/機能 テストを起動 ①機能を追加した 新コードをPush 継続的インテグレーションの例
9. CI 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②単体/機能 テストを起動 ①機能を追加した 新コードをPush ④レビューReady を通知 開発者 継続的インテグレーションの例
10. CI 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②単体/機能 テストを起動 ①機能を追加した 新コードをPush ④レビューReady を通知 開発者 ⑤コードレビュー 継続的インテグレーションの例
11. CI 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②単体/機能 テストを起動 ①機能を追加した 新コードをPush ④レビューReady を通知 開発者 ⑤レビューReady を通知 継続的インテグレーションの例 ここまでは 開発＋テスト の範囲 デプロイまで含めていく
12. 継続的デプロイとは (CD: Continuous Deployment) ・コード変更を契機として、自動的にビルド、 　テスト、および本番へのリリースを実行 （単なる用語として…） 　参考：継続デリバリ(CD: Continuous Delivery) 　・コード変更を契機として、自動的にビルド、 　　テスト、および本番へのリリース「準備」まで実行
13. 継続的デプロイの例 GitHub ①コードレビューで OKだったので 追加コードをマージ 開発者
14. 継続的デプロイの例 CI GitHub ①コードレビューで OKだったので 追加コードをマージ 開発者 ②マージされた イベントを通知
15. 継続的デプロイの例 CI GitHub ①コードレビューで OKだったので 追加コードをマージ 開発者 ②マージされた イベントを通知 ③新コードを 商用へ自動適用
16. CI GitHub ①コードレビューで OKだったので 追加コードをマージ 開発者 ②マージされた イベントを通知 ③新コードを 商用へ自動適用 全体像をまとめて 別の視点で見ると… 継続的デプロイの例
17. 引用: https://www.youtube.com/watch?time_continue=155&v=KvRBkDMDxXQ を参考に改変 Agility / Sustainability Iterative Development Continuous Integration Continuous Delivery 顧客価値を創出する流れ CI/CD含む全体像 Continuous Deployment
18. 今日の話 ・多くの場合、CI/CDの適用範囲はプログラム ・今日はそれをドキュメントへ適用 ・継続的にテストし、品質を作り込みつつ 　さらにデプロイまで実施していく話
19. エンジニアの気持ち的には ・Markdown / reStructuredText で書きたい
20. エンジニアの気持ち的には ・Markdown / reStructuredText で書きたい ・git で管理して、Pull Request Drivenで 　書きたい＆レビューしたい 　(Wordはgitに向いていない)
21. エンジニアの気持ち的には ・Markdown / reStructuredText で書きたい ・git で管理して、Pull Request Drivenで 　書きたい＆レビューしたい ・表記揺れなどのレビューは、 　人間がやるものじゃない
22. エンジニアの気持ち的には ・Markdown / reStructuredText で書きたい ・gitで管理して、Pull Request Drivenで 　書きたい＆レビューしたい ・表記ゆれなどのレビューは、 　人間がやるものじゃない CI/CD で自動化して やっていくしか！！
23. 最初にゴールの説明
24. SkyWay SDK リファレンス: お客様向けにJS SDKの使い方をまとめているドキュメント https://github.com/skyway/skyway-js-sdk-doc
25. CI/CDの全体像 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②CircleCI上で、 textlintを使った テスト実行 ①ブランチを切って 文書を追加(mkdocs) ④レビューReady を通知 その他 メンバ ⑤文書レビューして OKならマージ ⑥GitHub Pagesに 　masterをデプロイ
26. 以降、要素を個別に説明
27. CI/CDの構成 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②CircleCI上で、 textlintを使った テスト実行 ①ブランチを切って 文書を追加 (MkDocs) ④レビューReady を通知 その他 メンバ ⑤文書レビュー ⑥GitHub Pagesに 　masterをデプロイ
28. http://www.mkdocs.org/
29. MkDocs とは ・Markdownで書けるPythonベースの 　静的Webサイトジェネレータ 　 (類似のツールは Sphinx など)
30. MkDocs とは ・Markdownで書けるPythonベースの 　静的Webサイトジェネレータ 　 (類似のツールは Sphinx など) ・ビルドすると、HTML/JS/CSS を吐き出すので、 　それを任意の方法でデプロイする 　 e.g. Webサーバへ配置、S3へ置く、GitHub Pagesへ置く
31. MkDocs とは ・Markdownで書けるPythonベースの 　静的Webサイトジェネレータ 　 (類似のツールは Sphinx など) ・ビルドすると、HTML/JS/CSS を吐き出すので、 　それを任意の方法でデプロイする 　 e.g. Webサーバへ配置、S3へ置く、GitHub Pagesへ置く ・任意に拡張が可能 　 e.g. 独自にJSを追加、Themeを適用してデザイン変更
32. MkDocs - 使い方 // プロジェクト作成 $ mkdocs new my-project $ cd my-project // 実際にローカルで動かしてみる $ mkdocs serve -> http://127.0.0.1:8000 // GitHub Pages にデプロイする $ mkdocs gh-deploy
33. CI/CDの構成 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②CircleCI上で、 textlintを使った テスト実行 ①ブランチを切って 文書を追加(mkdocs) ④レビューReady を通知 その他 メンバ ⑤文書レビュー ⑥GitHub Pagesに 　masterをデプロイ
34. textlint とは ・lintは元々、C言語用の構文・文法チェッカだったが 　今では複数言語(e.g. html や golang )に対応
35. textlint とは ・lintは元々、C言語用の構文・文法チェッカだったが 　今では複数言語(e.g. html や golang )に対応 ・textlintは、lintの適用範囲を拡張して、 　文章に適用して、文章品質をテスト可能にしたツール 　(類似のツールは、 RedPen など)
36. textlint とは ・lintは元々、C言語用の構文・文法チェッカだったが 　今では複数言語(e.g. html や golang )に対応 ・textlintは、lintの適用範囲を拡張して、 　文章に適用して、文章品質をテスト可能にしたツール 　(類似のツールは、 RedPen など) ・テストするルールは、npm(モジュール)で 　好きなものをピックアップして追加可能
37. 引用: https://qiita.com/azu/items/e36501d25593d008f6ac textlint の例
38. textlint - 使い方(あとでまとめてデモ) インストール(今日は説明単純化のため、グローバル設定) $ npm install textlint --global WEB+DB PRESS用語統一ルールを設定 (Ref: https://gist.github.com/inao/f55e8232e150aee918b9) $ npm install textlint-rule-web-plus-db –global 実際にテスト(lint)する $ textlint --rule textlint-rule-web-plus-db docs/index.md
39. CI/CDの構成 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②CircleCI上で、 textlintを使った テスト実行 ①ブランチを切って 文書を追加(mkdocs) ④レビューReady を通知 その他 メンバ ⑤文書レビュー ⑥GitHub Pagesに 　masterをデプロイ
40. Circle CIとは ・CI as a Serviceの1つで、デファクトになりつつある 　(類似のSaaS: TravisCI, wercker, codeship など) https://trends.google.com/trends/
41. Circle CIとは ・CI as a Serviceの1つで、デファクトになりつつある ・YAML形式の定義ファイルで、任意のタスクを実行 使い方は これがほぼ全て 引用: https://circleci.com/docs/2.0/hello-world/
42. Circle CIとは ・CI as a Serviceの1つで、デファクトになりつつある ・YAML形式の定義ファイルで、任意のタスクを実行 使い方は これがほぼ全て この内容によって、 CI or CDするのか 決めるだけ
43. Circle CIとは ・CI as a Serviceの1つで、デファクトになりつつある ・YAML形式の定義ファイルで、任意のタスクを実行 ・WebHook / API 契機 だけでなく、 　cronライクなスケジュール機能もある triggers: 　- schedule: cron: "0 * * * *" e.g. 毎時実行したい場合
44. Circle CIとは ・CI as a Serviceの1つで、デファクトになりつつある ・YAML形式の定義ファイルで、任意のタスクを実行 ・WebHook / API 契機 だけでなく、 　cronライクなスケジュール機能もある ・おまけ 　・(完全に主観) やると分かるが爆速 　　e.g. オンプレDroneで10分 -> Circle CIで1分
45. CI/CDの構成 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②CircleCI上で、 textlintを使った テスト実行 ①ブランチを切って 文書を追加(mkdocs) ④レビューReady を通知 その他 メンバ ⑤文書レビュー ⑥GitHub Pagesに 　masterをデプロイ GitHub Pagesは CI/CDの本質じゃないので略
46. まとめ ・CI/CD を使って、ドキュメント品質を作り込んでいく ・SkyWayで使っているツール： 　・MkDocs (w/ material): 　　　Markdownの本文から静的Webサイト生成 　・textlint: 　　　任意のルールを設定して、文章自体をテスト 　・CircleCI: 　　　textlint実行およびGitHub Pagesのデプロイ