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
270
オンラインドキュメントへ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
AndroidデバイスにFTPサーバを建立する
e10dokup
0
250
インフラをつくるとはどういうことなのか、 あるいはPlatform Engineeringについて
nwiizo
5
2.6k
CZII - CryoET Object Identification 参加振り返り・解法共有
tattaka
0
360
OpenID BizDay#17 KYC WG活動報告(法人) / 20250219-BizDay17-KYC-legalidentity
oidfj
0
240
Cloud Spanner 導入で実現した快適な開発と運用について
colopl
1
650
エンジニアの育成を支える爆速フィードバック文化
sansantech
PRO
3
1.1k
RSNA2024振り返り
nanachi
0
580
データ資産をシームレスに伝達するためのイベント駆動型アーキテクチャ
kakehashi
PRO
2
530
JEDAI Meetup! Databricks AI/BI概要
databricksjapan
0
100
白金鉱業Meetup Vol.17_あるデータサイエンティストのデータマネジメントとの向き合い方
brainpadpr
6
750
個人開発から公式機能へ: PlaywrightとRailsをつなげた3年の軌跡
yusukeiwaki
11
3k
30分でわかる『アジャイルデータモデリング』
hanon52_
9
2.7k
Featured
See All Featured
Cheating the UX When There Is Nothing More to Optimize - PixelPioneers
stephaniewalter
280
13k
VelocityConf: Rendering Performance Case Studies
addyosmani
328
24k
A better future with KSS
kneath
238
17k
Docker and Python
trallard
44
3.3k
Fantastic passwords and where to find them - at NoRuKo
philnash
51
3k
Rebuilding a faster, lazier Slack
samanthasiow
80
8.8k
Rails Girls Zürich Keynote
gr2m
94
13k
Building Your Own Lightsaber
phodgson
104
6.2k
Embracing the Ebb and Flow
colly
84
4.6k
The Pragmatic Product Professional
lauravandoore
32
6.4k
How STYLIGHT went responsive
nonsquared
98
5.4k
Building Better People: How to give real-time feedback that sticks.
wjessup
367
19k
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のデプロイ