オンラインドキュメントへCI/CDを適用している話

オンラインドキュメントへCI/CDを適用している話

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