Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
オンラインドキュメントへCI・CDを適用している話 / apply CICD methods...
Search
iwashi
November 26, 2022
Technology
1
280
オンラインドキュメントへCI・CDを適用している話 / apply CICD methods to online documents
2018/1/24の社内勉強会で講演した資料です。
ドキュメントに対して、継続的インテグレーション・継続的デプロイを適用する話をまとめています。
iwashi
November 26, 2022
Tweet
Share
More Decks by iwashi
See All by iwashi
エンジニアリングが好きな私たちのためのエンジニアリングマネジャー入門 / Engineering management for the rest of us
iwashi86
22
5.2k
エレガントパズル 30分 ダイジェスト版/ Elegant Puzzle 30min Digest
iwashi86
5
560
エレガントパズル エンジニアのマネジメントという難問にあなたはどう立ち向かうのか / Elegant Puzzle
iwashi86
18
4k
ベロシティを高く保つ仕事のすすめ方 / Maintaining a High Velocity as Productivity Hacks
iwashi86
54
20k
マネージャー&リーダー向け 社内トレーニング / Training of management and leadership for Stockmark
iwashi86
65
32k
30分でわかる「エンジニアのためのドキュメントライティング」- インフラエンジニアBooks / Docs for Developers within 30 minutes
iwashi86
9
2.5k
エンジニアのためのドキュメントライティング / Docs for Developers
iwashi86
34
22k
なぜ変化を起こすのが難しいのか? - 数年以上にわたって難しさに向き合い・考え取り組んできたこと / The reason why changing organization is so hard - What I thought and faced for more than several years
iwashi86
60
88k
2015年 第4四半期の WebRTC 標準化 アップデート / 2015 update of WebRTC Standards
iwashi86
0
220
Other Decks in Technology
See All in Technology
レビューを増やしつつ 高評価維持するテクニック
tsuzuki817
1
820
ESXi で仮想化した ARM 環境で LLM を動作させてみるぞ
unnowataru
0
130
Exadata Database Service on Cloud@Customer セキュリティ、ネットワーク、および管理について
oracle4engineer
PRO
1
1.5k
明日からできる!技術的負債の返済を加速するための実践ガイド~『ホットペッパービューティー』の事例をもとに~
recruitengineers
PRO
3
500
AndroidXR 開発ツールごとの できることできないこと
donabe3
0
130
OpenID BizDay#17 KYC WG活動報告(法人) / 20250219-BizDay17-KYC-legalidentity
oidfj
0
290
SA Night #2 FinatextのSA思想/SA Night #2 Finatext session
satoshiimai
1
150
オブザーバビリティの観点でみるAWS / AWS from observability perspective
ymotongpoo
9
1.6k
デスクトップだけじゃないUbuntu
mtyshibata
0
550
IAMポリシーのAllow/Denyについて、改めて理解する
smt7174
2
140
Classmethod AI Talks(CATs) #17 司会進行スライド(2025.02.19) / classmethod-ai-talks-aka-cats_moderator-slides_vol17_2025-02-19
shinyaa31
0
160
RSNA2024振り返り
nanachi
0
620
Featured
See All Featured
Building Better People: How to give real-time feedback that sticks.
wjessup
367
19k
How to Ace a Technical Interview
jacobian
276
23k
Side Projects
sachag
452
42k
Improving Core Web Vitals using Speculation Rules API
sergeychernyshev
9
500
Sharpening the Axe: The Primacy of Toolmaking
bcantrill
40
2k
Adopting Sorbet at Scale
ufuk
74
9.2k
Statistics for Hackers
jakevdp
797
220k
Agile that works and the tools we love
rasmusluckow
328
21k
Dealing with People You Can't Stand - Big Design 2015
cassininazir
366
25k
For a Future-Friendly Web
brad_frost
176
9.5k
Six Lessons from altMBA
skipperchong
27
3.6k
Producing Creativity
orderedlist
PRO
344
39k
Transcript
Copyright © NTT Communications Corporation. All rights reserved. オンラインドキュメントへCI/CD を適用している話
NTTコミュニケーションズ / @iwashi86 2018.1.24 Cloud Academy
・岩瀬 義昌 / @iwashi86 ・SkyWayの中の人 ・技術面 ・WebRTC ・自動化 (CI/CD, IaC)
https://webrtc.ecl.ntt.com/
ドキュメントにCI/CDを 適用するメリット・やり方 について知ること (今後の業務の参考に) 本セッションのゴール
前提のおさらい
継続的インテグレーションとは (CI: Continuous Integration) ・ソフトウェアやシステムが正しく動作するか 継続的に確認しながら開発を進める手法 ・コンパイル・テスト・ビルドなどの一連の流れを 短期間で&継続的に結合
開発マシン GitHub ①機能を追加した 新コードをPush 継続的インテグレーションの例
CI 開発マシン GitHub ②単体/機能 テストを起動 ①機能を追加した 新コードをPush 継続的インテグレーションの例 e.g. オンプレ:
Jenkins/Concourse CI/Drone SaaS: Circle CI/Travis CI
CI 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②単体/機能 テストを起動 ①機能を追加した 新コードをPush 継続的インテグレーションの例
CI 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②単体/機能 テストを起動 ①機能を追加した 新コードをPush ④レビューReady
を通知 開発者 継続的インテグレーションの例
CI 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②単体/機能 テストを起動 ①機能を追加した 新コードをPush ④レビューReady
を通知 開発者 ⑤コードレビュー 継続的インテグレーションの例
CI 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②単体/機能 テストを起動 ①機能を追加した 新コードをPush ④レビューReady
を通知 開発者 ⑤レビューReady を通知 継続的インテグレーションの例 ここまでは 開発+テスト の範囲 デプロイまで含めていく
継続的デプロイとは (CD: Continuous Deployment) ・コード変更を契機として、自動的にビルド、 テスト、および本番へのリリースを実行 (単なる用語として…) 参考:継続デリバリ(CD: Continuous Delivery)
・コード変更を契機として、自動的にビルド、 テスト、および本番へのリリース「準備」まで実行
継続的デプロイの例 GitHub ①コードレビューで OKだったので 追加コードをマージ 開発者
継続的デプロイの例 CI GitHub ①コードレビューで OKだったので 追加コードをマージ 開発者 ②マージされた イベントを通知
継続的デプロイの例 CI GitHub ①コードレビューで OKだったので 追加コードをマージ 開発者 ②マージされた イベントを通知 ③新コードを
商用へ自動適用
CI GitHub ①コードレビューで OKだったので 追加コードをマージ 開発者 ②マージされた イベントを通知 ③新コードを 商用へ自動適用
全体像をまとめて 別の視点で見ると… 継続的デプロイの例
引用: https://www.youtube.com/watch?time_continue=155&v=KvRBkDMDxXQ を参考に改変 Agility / Sustainability Iterative Development Continuous Integration
Continuous Delivery 顧客価値を創出する流れ CI/CD含む全体像 Continuous Deployment
今日の話 ・多くの場合、CI/CDの適用範囲はプログラム ・今日はそれをドキュメントへ適用 ・継続的にテストし、品質を作り込みつつ さらにデプロイまで実施していく話
エンジニアの気持ち的には ・Markdown / reStructuredText で書きたい
エンジニアの気持ち的には ・Markdown / reStructuredText で書きたい ・git で管理して、Pull Request Drivenで 書きたい&レビューしたい
(Wordはgitに向いていない)
エンジニアの気持ち的には ・Markdown / reStructuredText で書きたい ・git で管理して、Pull Request Drivenで 書きたい&レビューしたい
・表記揺れなどのレビューは、 人間がやるものじゃない
エンジニアの気持ち的には ・Markdown / reStructuredText で書きたい ・gitで管理して、Pull Request Drivenで 書きたい&レビューしたい ・表記ゆれなどのレビューは、
人間がやるものじゃない CI/CD で自動化して やっていくしか!!
最初にゴールの説明
SkyWay SDK リファレンス: お客様向けにJS SDKの使い方をまとめているドキュメント https://github.com/skyway/skyway-js-sdk-doc
CI/CDの全体像 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②CircleCI上で、 textlintを使った テスト実行 ①ブランチを切って 文書を追加(mkdocs)
④レビューReady を通知 その他 メンバ ⑤文書レビューして OKならマージ ⑥GitHub Pagesに masterをデプロイ
以降、要素を個別に説明
CI/CDの構成 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②CircleCI上で、 textlintを使った テスト実行 ①ブランチを切って 文書を追加
(MkDocs) ④レビューReady を通知 その他 メンバ ⑤文書レビュー ⑥GitHub Pagesに masterをデプロイ
http://www.mkdocs.org/
MkDocs とは ・Markdownで書けるPythonベースの 静的Webサイトジェネレータ (類似のツールは Sphinx など)
MkDocs とは ・Markdownで書けるPythonベースの 静的Webサイトジェネレータ (類似のツールは Sphinx など) ・ビルドすると、HTML/JS/CSS を吐き出すので、
それを任意の方法でデプロイする e.g. Webサーバへ配置、S3へ置く、GitHub Pagesへ置く
MkDocs とは ・Markdownで書けるPythonベースの 静的Webサイトジェネレータ (類似のツールは Sphinx など) ・ビルドすると、HTML/JS/CSS を吐き出すので、
それを任意の方法でデプロイする e.g. Webサーバへ配置、S3へ置く、GitHub Pagesへ置く ・任意に拡張が可能 e.g. 独自にJSを追加、Themeを適用してデザイン変更
MkDocs - 使い方 // プロジェクト作成 $ mkdocs new my-project $
cd my-project // 実際にローカルで動かしてみる $ mkdocs serve -> http://127.0.0.1:8000 // GitHub Pages にデプロイする $ mkdocs gh-deploy
CI/CDの構成 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②CircleCI上で、 textlintを使った テスト実行 ①ブランチを切って 文書を追加(mkdocs)
④レビューReady を通知 その他 メンバ ⑤文書レビュー ⑥GitHub Pagesに masterをデプロイ
textlint とは ・lintは元々、C言語用の構文・文法チェッカだったが 今では複数言語(e.g. html や golang )に対応
textlint とは ・lintは元々、C言語用の構文・文法チェッカだったが 今では複数言語(e.g. html や golang )に対応 ・textlintは、lintの適用範囲を拡張して、 文章に適用して、文章品質をテスト可能にしたツール
(類似のツールは、 RedPen など)
textlint とは ・lintは元々、C言語用の構文・文法チェッカだったが 今では複数言語(e.g. html や golang )に対応 ・textlintは、lintの適用範囲を拡張して、 文章に適用して、文章品質をテスト可能にしたツール
(類似のツールは、 RedPen など) ・テストするルールは、npm(モジュール)で 好きなものをピックアップして追加可能
引用: https://qiita.com/azu/items/e36501d25593d008f6ac textlint の例
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
CI/CDの構成 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②CircleCI上で、 textlintを使った テスト実行 ①ブランチを切って 文書を追加(mkdocs)
④レビューReady を通知 その他 メンバ ⑤文書レビュー ⑥GitHub Pagesに masterをデプロイ
Circle CIとは ・CI as a Serviceの1つで、デファクトになりつつある (類似のSaaS: TravisCI, wercker, codeship
など) https://trends.google.com/trends/
Circle CIとは ・CI as a Serviceの1つで、デファクトになりつつある ・YAML形式の定義ファイルで、任意のタスクを実行 使い方は これがほぼ全て 引用:
https://circleci.com/docs/2.0/hello-world/
Circle CIとは ・CI as a Serviceの1つで、デファクトになりつつある ・YAML形式の定義ファイルで、任意のタスクを実行 使い方は これがほぼ全て この内容によって、
CI or CDするのか 決めるだけ
Circle CIとは ・CI as a Serviceの1つで、デファクトになりつつある ・YAML形式の定義ファイルで、任意のタスクを実行 ・WebHook / API
契機 だけでなく、 cronライクなスケジュール機能もある triggers: - schedule: cron: "0 * * * *" e.g. 毎時実行したい場合
Circle CIとは ・CI as a Serviceの1つで、デファクトになりつつある ・YAML形式の定義ファイルで、任意のタスクを実行 ・WebHook / API
契機 だけでなく、 cronライクなスケジュール機能もある ・おまけ ・(完全に主観) やると分かるが爆速 e.g. オンプレDroneで10分 -> Circle CIで1分
CI/CDの構成 開発マシン GitHub ③テスト結果 (Pass/Fail)を返却 ②CircleCI上で、 textlintを使った テスト実行 ①ブランチを切って 文書を追加(mkdocs)
④レビューReady を通知 その他 メンバ ⑤文書レビュー ⑥GitHub Pagesに masterをデプロイ GitHub Pagesは CI/CDの本質じゃないので略
まとめ ・CI/CD を使って、ドキュメント品質を作り込んでいく ・SkyWayで使っているツール: ・MkDocs (w/ material): Markdownの本文から静的Webサイト生成 ・textlint: 任意のルールを設定して、文章自体をテスト
・CircleCI: textlint実行およびGitHub Pagesのデプロイ