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

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

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