sphinx-revealjs
（自分を含む）日本で sphinx-revealjs を利用している人向けの、README補完+αのテキスト。
概要
sphinx-revealjs は、reStrucuredTextのソースをReveal.js形式のプレゼンテーションに変換するためのSphinx拡張。
リリース周りの
自分の中である程度決めてはいるものの、英文として変化するのがちょっと手間なリリース戦略周りについて書き起こす。
セマンティックバージョニングの採用
基本思想として セマンティックバージョニング2.0.0 を採用している。 そのため、基本的には以下の通りの更新を実施している。
メジャーバージョンの更新条件
ライブラリとして広報互換性を失う更新を行う
マイナーバージョンの更新条件
広報互換性を維持しつつ、新しい機能を追加する
後述の依存処理ルールに基づいて、非推奨な要件が発生する
パッチバージョンの更新条件
ライブラリとしての機能に発生していた不備を改修する
Reveal.jsのマイナーバージョン以下の更新を取り込む
リリースのクールタイム
sphinx-revealjs の開発は、「自分がプレゼンテーションであると嬉しい」機能を実装するのが基本スタイルとなっている。
そのため、マイナーバージョン以上の更新に対するクールタイムを用意して、意識的なドッグフーディングを行うようにしている。
目安としては、以下のとおり。
マイナーバージョン更新後は 1ヶ月 を標準クールタイムとして、この期間はパッチバージョン更新のみを行う
メジャーバージョン更新後は 最低3ヶ月 を標準クールタイムとして、この期間はマイナーバージョン更新までしか行わない
依存先との付き合い方
この sphinx-revealjs は Reveal.js を用いた Python 製の Sphinx の拡張ライブラリという立ち位置になっている。
つまり、これらの3プロダクトに直接依存している。
いずれもアクティブなプロダクトであるため、それなりのペースで更新が行われていくのだが、 なるべくならバージョンの変化に追従できる体制を取ることが望ましい。
そこで、ある程度の指標として以下のような方針を定めている。
対Reveal.js
sphinx-revealjs はSphinxの拡張ビルダーとしてReveal.js向けのHTMLを生成する仕組みとなっている。
Reveal.jsはフロントエンド系のライブラリであり、CDN提供されていることも併せて、
比較的最新バージョンのものがすぐに使われる傾向が強い。
そのため、「可能な限り追従する」体制を取るために、GitHub Actionsで監視を行いつつ、以下の方針を取るようにしている。
マイナー以下のバージョン更新が発生した場合は、速やかに取り込みを行って
sphinx-revealjsのパッチバージョン更新として対応するメジャーなバージョン更新が発生したっ場合は、以下のスタイルを基準に対応する
X.0が登場した時点で、マイナーバージョン更新として「新旧両バージョンの取り込み」を行う。この時点では「新バージョンの利用は実験的」扱いとするその後に
X.1が出るまでは、上記更新以降から「バージョン選択制・どちらのバージョンでもプレゼンテーション表現に変化がない」体制を維持するX.1が出たあたりで、まずは「旧バージョン利用を非推奨」とするマイナーバージョン更新を行う次のメジャーバージョン更新のタイミングで、旧バージョンの取り込みをやめる
対Sphinx
課題
ぼんやりと考えているけど、文字化化がまだ
対Python
課題
ぼんやりと考えているけど、文字化化がまだ