OpenShift.Run 2023 2 0 2 3 / 0 1 / 2 7 @ l o f t k u n OpenShiftの リリースノートを 整理してみた

$ whoami loftkun - IT Specialist at IBM ( ex Yahoo! ) - RHEL / OSS ( OpenShift, GitLab, etc ) - Side Job (2021) : IT lecturer at Kyushu University Lab - Python ( Anaconda ) - Staff of VS Code Conference Japan 2021, 2022 - 2023 - Presentation at - IBM Cloud Festa Online 2022 Summer - VS Code Conference Japan 2021 - OpenShift.Run Winter 2020 - CloudNative Days Kansai 2019 Meetup - ふくばねてす (登壇皆勤) - 独学Piano、観る＆指す将、蒸留酒

関連発表 2022/07/29 IBM Cloud Festa Online 2022 Summer https://speakerdeck.com/loftkun/ibm-cloud-festa-online-2022-summer-openshift-support OpenShiftのサポートを始めるぞ！高頻度で更新されるOSSを 効果的にキャッチアップする仕組みを考えました！

Agenda リリースノート の活用事例 を見てみよう の構成 閲覧の課題 を整理してみた

リリースノート の活用事例

リリースサイクルへの追従 2021/07/27 4.8 GAリリース 2021/10/18 4.9 GAリリース 2022/03/10 4.10 GAリリース 2022/08/10 4.11 GAリリース 2023/01/17 4.12 GAリリース サポート終了になる前に次のバージョンについて把握したい

構築・アップデートに備える 構築手順の変更はないか、移行先バージョンで非推奨・削除と なっている機能はないか確認し、予め備えておきたい

リリースノートを 見てみよう

リリースノートを見てみよう Product Documentation for OpenShift Container Platform https://access.redhat.com/documentation/ja-jp/openshift_container_platform 本発表では redhat.com の日本語版を対象としています。 docs.openshift.com には英語版の原本があります。

日本語に 切り替え可能

ドキュメント内全体を検索したい場合 は Single-page がおすすめ

目次 章構成を次に ご紹介します

リリースノートの 構成

章構成の変化 章タイトル 4.6 4.7 4.8 4.9 4.10 4.11 4.12 本リリースについて 1.1. 1.1. 1.1. 1.1. 1.1. 1.1. 1.1. 多様性を受け入れるオープンソースの強化 1.2. 1.2. OpenShift ContainerPlatform のレイヤー化された 依存関係にあるコンポーネントのサポートと互換性 1.3. 1.2. 1.2. 1.2. 1.2. 新機能および改良された機能 1.2. 1.3. 1.4. 1.3. 1.3. 1.3. 1.3. 主な技術上の変更点 1.3. 1.4. 1.5. 1.4. 1.4. 1.4. 1.4. 非推奨および削除された機能 1.4. 1.5. 1.6. 1.5. 1.5. 1.5. 1.5. バグ修正 1.5. 1.6. 1.7. 1.6. 1.6. 1.6. 1.6. テクノロジープレビューの機能 1.6. 1.7. 1.8. 1.7. 1.7. 1.7. 1.7. 既知の問題 1.7. 1.8. 1.9. 1.8. 1.8. 1.8. 1.8. エラータの非同期更新 1.8. 1.9. 1.10. 1.9. 1.9. 1.9. 1.9. • 最近( OCP4.9以降)は、 1.1. ～ 1.9. の 9章構成で推移 • 今後も変化する可能性はありそう

“本リリースについて” GA日、k8sバージョン などが分かります

“多様性を受け入れるオープンソースの強化” 現状、 OCP 4.7, 4.8 のみ 記載されている章

“OpenShift ContainerPlatform のレイヤー化された 依存関係にあるコンポーネントのサポートと互換性” OpneShiftと連携・統合 されるコンポーネント については別文献

“OpenShift ContainerPlatform のレイヤー化された 依存関係にあるコンポーネントのサポートと互換性” これらのコンポーネントついては それぞれのリリースサイクルでリ リースされたりする。 詳細は別文献となっている

“新機能および機能拡張” 分野ごとに 章立てされている

“新機能および機能拡張” OCP 4.12 ではこのような章構成 となっている

“主な技術上の変更点” 機能の追加や削除ではな い”変更点”の章

“非推奨および削除された機能” 非推奨：まだ使用できるが、今 後削除される可能性が高い 削除：今回のリリースで削除さ れた機能、もう使用できない

“バグ修正” Red Hat Bugzilla へのリンクが記 載されていて詳細内容を 確認可能なバグもある

“テクノロジープレビューの機能” TP : 今後 GA となる可能性のある機能

“テクノロジープレビューの機能” GA となった 削除された TPとして出現した 章のタイトルからは TP に関する章である印象を受けやすいが、 実際には、 GA となったり 削除された 機能も把握できる章となっています。

“既知の問題” 使用前に一読したり、 不具合の可能性のある挙動に出くわ した場合に確認すると良い章です

“エラータの非同期更新” 追加情報として、以下のような情報が 不定期に追記されます ( 月数件くらい ) ・バグ修正 ・既知の問題 ・機能、特長 ・削除された機能 そのため、常に最新のリリースノートを参照 するのがおすすめです。 なお、この章以外でも、 記載内容の 変更/追記/挿入/削除 は不定期に発生します。

まとめ • リリースノートの内容は不定期に更新されるぞ – 常に最新版を参照するのがおすすすめです • 特に、”エラータの非同期更新”の章はどんどん追記されていくぞ • その他の章も、変更・追記・挿入・削除は 不定期に発生するぞ – 特に挿入が行われると、章番号もずれていく – 章番号でポイントしたり管理するのはおすすめできません 不定期に更新されていくリリースノートを、 どのように整理しているかご紹介していきます！

リリースノート 閲覧の課題

前回読んだときから、何か が変わってしまっているか もしれないな・・・ 不定期更新が行われる

キーワードで検索すれば、出現 する単語数は分かるが、 意味のある情報の単位としては、 何個あるんだ？ 意味のある単位での検索性

他のバージョンのドキュメン トも見たいな。 ブラウザのタブが増えていく なあ。 ドキュメント間横断での検索性

まとめ • 不定期に更新されるので、更新日と更新箇所を把握したい •意味のある単位で列挙できるようにしたい • ドキュメント間横断で検索したい このような課題に対して、リリースノートを、 どのように整理しているかご紹介していきます！

リリースノートを 整理する

ドキュメント ドキュメントを分解しカードとする、 カードにラベリングし、Gitで管理

ドキュメント カードに分解 → ドキュメントを分解しカードとする、 カードにラベリングし、Gitで管理 ⚫ 章ごとに適切な分解粒度を定め、その粒度で分解してカード化

ドキュメント カードに分解 カードにラベル付け → → 実際は複数のラベルが付きます ドキュメントを分解しカードとする、 カードにラベリングし、Gitで管理 ⚫ 章ごとに適切な分解粒度を定め、その粒度で分解してカード化 ⚫ カードにラベル付け( バージョン、章の種類、コンポーネント名 )

ドキュメント カードに分解 カードにラベル付け Gitでバージョン管理 → → 実際は複数のラベルが付きます ドキュメントを分解しカードとする、 カードにラベリングし、Gitで管理 ⚫ 章ごとに適切な分解粒度を定め、その粒度で分解してカード化 ⚫ カードにラベル付け( バージョン、章の種類、コンポーネント名 ) ⚫ カード群をGitでバージョン管理

ドキュメント カードに分解 カードにラベル付け Gitでバージョン管理 ラベルで絞り込み ドキュメント間横断検索が実現 → → → 実際は複数のラベルが付きます ドキュメントを分解しカードとする、 カードにラベリングし、Gitで管理 ⚫ 章ごとに適切な分解粒度を定め、その粒度で分解してカード化 ⚫ カードにラベル付け( バージョン、章の種類、コンポーネント名 ) ⚫ カード群をGitでバージョン管理 ⚫ カード群をキーワードで検索したりラベルで絞り込んで閲覧できるようにする ( GitHub の Issueを利用 )

付与するラベル リリースノートの章 ラベル名 ( section-* ) 本リリースについて about 多様性を受け入れるオープンソースの強化 inclusive OpenShift ContainerPlatform のレイヤー化された 依存関係にあるコンポーネントのサポートと互換性 dependant 新機能および改良された機能 feature 主な技術上の変更点 change 非推奨および削除された機能 冒頭文 deprecated-removed 非推奨の機能 deprecated 削除された機能 removed バグ修正 bug テクノロジープレビューの機能 tp 既知の問題 known エラータの非同期更新 errata 以下なども付与 ⚫ バージョン ⚫ 新機能及び改良された機能のコンポーネント名

整理した結果

カード化 リリースノートのHTMLをマークダウンに変換してカード化

ラベリング 付与するラベルは、”バージョン”、”セクション( ドキュメントのどの章か )”、”コンポーネント名”、 その他頻出キーワード

章ごとのフォルダに格納 GitHubで管理

GitHubでのカードのプレビュー ラベル タイトル・本文 GitHubを使用していることで、プレビューができ、検索機能も使える

• 出現している単語数は分かる • 意味のある単位での閲覧は難しい • 一瞬で115件のカードがあることが分かる • キーワードに関連するカードのみ一覧で見れる • 複数ドキュメント(複数バージョン) の情報を横断検索できている 例) “rchos” で検索 絞り込み

絞り込み バージョンのラベルを指定することで目的のバー ジョンのみに絞り込める • 一瞬で18枚のカードを絞り込める • 出現している単語数は分かる • 意味のある単位での閲覧は難しい

まとめ • 不定期に更新される懸念は定期的なGitコミットで解消 •カード化することで意味のある単位で取り扱い可能 • 複数ドキュメントをカード化することで、ドキュメント間の横断 検索も可能 リリースノートを整理している事例を ご紹介しました！

数値で見る リリースノート

OpenShiftバージョンとカード枚数の関係 新しいバージョンはカード数が少なく見えるが、 不定期で追加されるエラータの非同期更新の量がまだ少ないためと思われる

新機能及び改良された機能のコンポーネント名もしくは分野名 ( concepts ) ネットワークの話題が圧倒的に多く、 インストール&アップデートの話題が続く

まとめ

OpenShiftのリリースノートを 整理してみた • リリースノートは リリースサイクルへの追従、構築・アップデートの準備に活用できる • 課題もある – 不定期に更新される – ブラウザでの閲覧性 • 整理してみた – ドキュメントを意味のある単位( = “カード” ) に分解し、分類・絞り込み用のラベルを付与した – リリースノートの不定期の更新をGitで履歴管理するようにした – 複数ドキュメントをカード化し、ドキュメント間の横断検索を可能とした ドキュメントの整理や把握に役立ちましたら幸いです！

ご清聴ありがとう ございました！