$30 off During Our Annual Pro Sale. View Details »

OpenShiftのリリースノートを整理してみた

loftkun
January 27, 2023

 OpenShiftのリリースノートを整理してみた

2023/01/27(金) OpenShift.Run 2023
https://openshift.connpass.com/event/234302/

loftkun

January 27, 2023
Tweet

More Decks by loftkun

Other Decks in Technology

Transcript

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

    View Slide

  2. $ 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、観る&指す将、蒸留酒

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  6. リリースサイクルへの追従
    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リリース
    サポート終了になる前に次のバージョンについて把握したい

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  10. 日本語に
    切り替え可能

    View Slide

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

    View Slide

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

    View Slide

  13. リリースノートの
    構成

    View Slide

  14. 章構成の変化
    章タイトル 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章構成で推移
    • 今後も変化する可能性はありそう

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  36. ドキュメント カードに分解

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  41. 整理した結果

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  52. まとめ

    View Slide

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

    View Slide

  54. ご清聴ありがとう
    ございました!

    View Slide