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

Slide 1

Slide 1 text

Slide 2

Slide 2 text

・岩瀬義昌 / @iwashi86 ・SkyWayの中の人・技術面　・WebRTC 　・自動化 (CI/CD, IaC) https://webrtc.ecl.ntt.com/

Slide 3

Slide 3 text

ドキュメントにCI/CDを適用するメリット・やり方について知ること (今後の業務の参考に) 本セッションのゴール

Slide 4

Slide 4 text

前提のおさらい

Slide 5

Slide 5 text

継続的インテグレーションとは (CI: Continuous Integration) ・ソフトウェアやシステムが正しく動作するか　継続的に確認しながら開発を進める手法・コンパイル・テスト・ビルドなどの一連の流れを　短期間で＆継続的に結合

Slide 6

Slide 6 text

開発マシン GitHub ①機能を追加した新コードをPush 継続的インテグレーションの例

Slide 7

Slide 7 text

CI 開発マシン GitHub ②単体/機能テストを起動 ①機能を追加した新コードをPush 継続的インテグレーションの例 e.g. オンプレ: Jenkins/Concourse CI/Drone SaaS: Circle CI/Travis CI

Slide 8

Slide 8 text

CI 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②単体/機能テストを起動 ①機能を追加した新コードをPush 継続的インテグレーションの例

Slide 9

Slide 9 text

CI 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②単体/機能テストを起動 ①機能を追加した新コードをPush ④レビューReady を通知開発者継続的インテグレーションの例

Slide 10

Slide 10 text

CI 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②単体/機能テストを起動 ①機能を追加した新コードをPush ④レビューReady を通知開発者 ⑤コードレビュー継続的インテグレーションの例

Slide 11

Slide 11 text

CI 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②単体/機能テストを起動 ①機能を追加した新コードをPush ④レビューReady を通知開発者 ⑤レビューReady を通知継続的インテグレーションの例ここまでは開発＋テストの範囲デプロイまで含めていく

Slide 12

Slide 12 text

継続的デプロイとは (CD: Continuous Deployment) ・コード変更を契機として、自動的にビルド、　テスト、および本番へのリリースを実行（単なる用語として…）　参考：継続デリバリ(CD: Continuous Delivery) 　・コード変更を契機として、自動的にビルド、　　テスト、および本番へのリリース「準備」まで実行

Slide 13

Slide 13 text

継続的デプロイの例 GitHub ①コードレビューで OKだったので追加コードをマージ開発者

Slide 14

Slide 14 text

継続的デプロイの例 CI GitHub ①コードレビューで OKだったので追加コードをマージ開発者 ②マージされたイベントを通知

Slide 15

Slide 15 text

継続的デプロイの例 CI GitHub ①コードレビューで OKだったので追加コードをマージ開発者 ②マージされたイベントを通知 ③新コードを商用へ自動適用

Slide 16

Slide 16 text

CI GitHub ①コードレビューで OKだったので追加コードをマージ開発者 ②マージされたイベントを通知 ③新コードを商用へ自動適用全体像をまとめて別の視点で見ると… 継続的デプロイの例

Slide 17

Slide 17 text

引用: https://www.youtube.com/watch?time_continue=155&v=KvRBkDMDxXQ を参考に改変 Agility / Sustainability Iterative Development Continuous Integration Continuous Delivery 顧客価値を創出する流れ CI/CD含む全体像 Continuous Deployment

Slide 18

Slide 18 text

今日の話・多くの場合、CI/CDの適用範囲はプログラム・今日はそれをドキュメントへ適用・継続的にテストし、品質を作り込みつつ　さらにデプロイまで実施していく話

Slide 19

Slide 19 text

エンジニアの気持ち的には・Markdown / reStructuredText で書きたい

Slide 20

Slide 20 text

エンジニアの気持ち的には・Markdown / reStructuredText で書きたい・git で管理して、Pull Request Drivenで　書きたい＆レビューしたい　(Wordはgitに向いていない)

Slide 21

Slide 21 text

エンジニアの気持ち的には・Markdown / reStructuredText で書きたい・git で管理して、Pull Request Drivenで　書きたい＆レビューしたい・表記揺れなどのレビューは、　人間がやるものじゃない

Slide 22

Slide 22 text

エンジニアの気持ち的には・Markdown / reStructuredText で書きたい・gitで管理して、Pull Request Drivenで　書きたい＆レビューしたい・表記ゆれなどのレビューは、　人間がやるものじゃない CI/CD で自動化してやっていくしか！！

Slide 23

Slide 23 text

最初にゴールの説明

Slide 24

Slide 24 text

SkyWay SDK リファレンス: お客様向けにJS SDKの使い方をまとめているドキュメント https://github.com/skyway/skyway-js-sdk-doc

Slide 25

Slide 25 text

CI/CDの全体像開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②CircleCI上で、 textlintを使ったテスト実行 ①ブランチを切って文書を追加(mkdocs) ④レビューReady を通知その他メンバ ⑤文書レビューして OKならマージ ⑥GitHub Pagesに　masterをデプロイ

Slide 26

Slide 26 text

以降、要素を個別に説明

Slide 27

Slide 27 text

CI/CDの構成開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②CircleCI上で、 textlintを使ったテスト実行 ①ブランチを切って文書を追加 (MkDocs) ④レビューReady を通知その他メンバ ⑤文書レビュー ⑥GitHub Pagesに　masterをデプロイ

Slide 28

Slide 28 text

http://www.mkdocs.org/

Slide 29

Slide 29 text

MkDocs とは・Markdownで書けるPythonベースの　静的Webサイトジェネレータ　 (類似のツールは Sphinx など)

Slide 30

Slide 30 text

MkDocs とは・Markdownで書けるPythonベースの　静的Webサイトジェネレータ　 (類似のツールは Sphinx など) ・ビルドすると、HTML/JS/CSS を吐き出すので、　それを任意の方法でデプロイする　 e.g. Webサーバへ配置、S3へ置く、GitHub Pagesへ置く

Slide 31

Slide 31 text

MkDocs とは・Markdownで書けるPythonベースの　静的Webサイトジェネレータ　 (類似のツールは Sphinx など) ・ビルドすると、HTML/JS/CSS を吐き出すので、　それを任意の方法でデプロイする　 e.g. Webサーバへ配置、S3へ置く、GitHub Pagesへ置く・任意に拡張が可能　 e.g. 独自にJSを追加、Themeを適用してデザイン変更

Slide 32

Slide 32 text

MkDocs - 使い方 // プロジェクト作成 $ mkdocs new my-project $ cd my-project // 実際にローカルで動かしてみる $ mkdocs serve -> http://127.0.0.1:8000 // GitHub Pages にデプロイする $ mkdocs gh-deploy

Slide 33

Slide 33 text

CI/CDの構成開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②CircleCI上で、 textlintを使ったテスト実行 ①ブランチを切って文書を追加(mkdocs) ④レビューReady を通知その他メンバ ⑤文書レビュー ⑥GitHub Pagesに　masterをデプロイ

Slide 34

Slide 34 text

textlint とは・lintは元々、C言語用の構文・文法チェッカだったが　今では複数言語(e.g. html や golang )に対応

Slide 35

Slide 35 text

textlint とは・lintは元々、C言語用の構文・文法チェッカだったが　今では複数言語(e.g. html や golang )に対応・textlintは、lintの適用範囲を拡張して、　文章に適用して、文章品質をテスト可能にしたツール　(類似のツールは、 RedPen など)

Slide 36

Slide 36 text

textlint とは・lintは元々、C言語用の構文・文法チェッカだったが　今では複数言語(e.g. html や golang )に対応・textlintは、lintの適用範囲を拡張して、　文章に適用して、文章品質をテスト可能にしたツール　(類似のツールは、 RedPen など) ・テストするルールは、npm(モジュール)で　好きなものをピックアップして追加可能

Slide 37

Slide 37 text

引用: https://qiita.com/azu/items/e36501d25593d008f6ac textlint の例

Slide 38

Slide 38 text

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

Slide 39

Slide 39 text

Slide 40

Slide 40 text

Circle CIとは・CI as a Serviceの1つで、デファクトになりつつある　(類似のSaaS: TravisCI, wercker, codeship など) https://trends.google.com/trends/

Slide 41

Slide 41 text

Circle CIとは・CI as a Serviceの1つで、デファクトになりつつある・YAML形式の定義ファイルで、任意のタスクを実行使い方はこれがほぼ全て引用: https://circleci.com/docs/2.0/hello-world/

Slide 42

Slide 42 text

Circle CIとは・CI as a Serviceの1つで、デファクトになりつつある・YAML形式の定義ファイルで、任意のタスクを実行使い方はこれがほぼ全てこの内容によって、 CI or CDするのか決めるだけ

Slide 43

Slide 43 text

Circle CIとは・CI as a Serviceの1つで、デファクトになりつつある・YAML形式の定義ファイルで、任意のタスクを実行・WebHook / API 契機だけでなく、　cronライクなスケジュール機能もある triggers: 　- schedule: cron: "0 * * * *" e.g. 毎時実行したい場合

Slide 44

Slide 44 text

Circle CIとは・CI as a Serviceの1つで、デファクトになりつつある・YAML形式の定義ファイルで、任意のタスクを実行・WebHook / API 契機だけでなく、　cronライクなスケジュール機能もある・おまけ　・(完全に主観) やると分かるが爆速　　e.g. オンプレDroneで10分 -> Circle CIで1分

Slide 45

Slide 45 text

CI/CDの構成開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②CircleCI上で、 textlintを使ったテスト実行 ①ブランチを切って文書を追加(mkdocs) ④レビューReady を通知その他メンバ ⑤文書レビュー ⑥GitHub Pagesに　masterをデプロイ GitHub Pagesは CI/CDの本質じゃないので略

Slide 46

Slide 46 text

まとめ・CI/CD を使って、ドキュメント品質を作り込んでいく・SkyWayで使っているツール：　・MkDocs (w/ material): 　　　Markdownの本文から静的Webサイト生成　・textlint: 　　　任意のルールを設定して、文章自体をテスト　・CircleCI: 　　　textlint実行およびGitHub Pagesのデプロイ