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
n=1の経験が紡ぐエンジニアリングマネジメントの可能性 / The Possibilities of Engineering Management from n=1 Experiences
iwashi86
11
1.5k
エンジニアリングが好きな私たちのためのエンジニアリングマネジャー入門 / Engineering management for the rest of us
iwashi86
22
5.2k
エレガントパズル 30分 ダイジェスト版/ Elegant Puzzle 30min Digest
iwashi86
5
570
エレガントパズル エンジニアのマネジメントという難問にあなたはどう立ち向かうのか / 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
Other Decks in Technology
See All in Technology
Iceberg Meetup Japan #1 : Iceberg and Databricks
databricksjapan
0
230
短縮URLをお手軽に導入しよう
nakasho
0
120
Swiftの “private” を テストする / Testing Swift "private"
yutailang0119
0
140
データマネジメントのトレードオフに立ち向かう
ikkimiyazaki
6
1.2k
OpenID BizDay#17 みんなの銀行による身元確認結果の活用 / 20250219-BizDay17-KYC-minna-no-ginko
oidfj
0
180
「正しく」失敗できる チームの作り方 〜リアルな事例から紐解く失敗を恐れない組織とは〜 / A team that can fail correctly
i35_267
2
600
全文検索+セマンティックランカー+LLMの自然文検索サ−ビスで得られた知見
segavvy
2
140
次世代KYC活動報告 / 20250219-BizDay17-KYC-nextgen
oidfj
0
440
LINEギフトにおけるバックエンド開発
lycorptech_jp
PRO
0
140
生成 AI プロダクトを育てる技術 〜データ品質向上による継続的な価値創出の実践〜
icoxfog417
PRO
5
1.8k
Raycast AI APIを使ってちょっと便利な拡張機能を作ってみた / created-a-handy-extension-using-the-raycast-ai-api
kawamataryo
0
170
Share my, our lessons from the road to re:Invent
naospon
0
120
Featured
See All Featured
個人開発の失敗を避けるイケてる考え方 / tips for indie hackers
panda_program
100
18k
Imperfection Machines: The Place of Print at Facebook
scottboms
267
13k
Typedesign – Prime Four
hannesfritz
40
2.5k
Intergalactic Javascript Robots from Outer Space
tanoku
270
27k
Designing Dashboards & Data Visualisations in Web Apps
destraynor
231
53k
Why Our Code Smells
bkeepers
PRO
336
57k
Raft: Consensus for Rubyists
vanstee
137
6.8k
Agile that works and the tools we love
rasmusluckow
328
21k
Site-Speed That Sticks
csswizardry
4
390
YesSQL, Process and Tooling at Scale
rocio
172
14k
Java REST API Framework Comparison - PWX 2021
mraible
28
8.4k
How to Create Impact in a Changing Tech Landscape [PerfNow 2023]
tammyeverts
49
2.3k
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のデプロイ