OSSを「自分用フォーク」で運用する技術 — 公式の更新と共存する改造の作法

前回・前々回の記事で、Obsidian の Claude 用プラグイン「Claudian」（Yishen Tu 氏作・MIT ライセンス）を改造した話を書きました。入力まわりの修正が1件、タブ UI の作り替えが8件。これらはすべて「フォーク」——公式のソースコードを手元に複製し、自分用の変更を積んだ別系統——として運用しています。

フォーク運用で本当に難しいのは、改造コードを書くことではありません。公式が更新され続ける中で、自分の変更を維持し続ける仕組みの方です。今回はその作法をまとめます。

フォークに留めるか、本家に返すか

まず、すべての変更をフォークに溜めるべきではありません。判断軸はシンプルで、「この変更は、他のすべてのユーザーにとっても正しいか？」です。

本家に返すべきもの: 日本語 IME の変換確定 Enter で誤送信されるバグ修正。日本語・中国語・韓国語ユーザー全員に効く、誰にとっても正しい変更です。こういうものはプルリクエストとして本家に提案する候補になります
フォークに留めるもの: タブ一覧のドロワー化のような、自分の使い方に最適化した UI 変更。他のユーザーには余計なお世話かもしれない変更を本家に送っても、メンテナーを困らせるだけです

なお、改造・再配布の前提としてライセンスの確認は必須です。Claudian は MIT ライセンスなので、著作権表示を維持すれば自由に改変できます。

日常のワークフロー — ソースと成果物を区別する

運用の基本形はこうです。

公式リポジトリをローカルにクローンし、src/ を編集する
npm run build でビルドする
成果物（main.js / styles.css / manifest.json）を Obsidian のプラグインフォルダへコピーする
プラグインをオフ→オンで反映する

ここで一度失敗したのが、ソースと成果物の区別です。リポジトリ直下の styles.css を直接編集したら、次のビルドで変更が消えました。このファイルは src/style/ 配下のモジュール CSS を連結して生成されるビルド成果物だったのです。他人のリポジトリを触るときは、「このファイルは人が書いたものか、機械が作ったものか」を最初に確認する。gitignore にビルド出力が入っているかを見るのが手っ取り早い方法です。

テストと型チェックもフォーク側で回し続けます。ポイントは、自分の改造によって生じた既存テストとの食い違いを「既知のずれ」として記録しておくこと。そうしておけば、新しい変更を入れたときに「前からあるエラー」と「いま自分が壊したもの」を混同せずに済みます。

最大のリスク — 公式更新による上書き

フォーク運用の最大の事故は、アプリ本体のプラグイン更新機能が公式版を上書きしてくることです。Obsidian でプラグインの更新を当てると、カスタム版の main.js は公式版に置き換えられ、改造はすべて消えます。

これを「起きないようにする」のではなく、「起きても数分で復旧できる」ように備えます。

正本は常に git リポジトリ側に置く。プラグインフォルダ内のファイルは使い捨てのコピーと考える
公式の新バージョンを取り込むときは git pull でマージし、再ビルドして再配備する
改造前の公式版ファイル一式も、切り戻し用にバックアップフォルダへ保管しておく

公式仕様の「名残」と対話する

改造を重ねると、公式の元設計と自分の変更が噛み合わなくなる瞬間が来ます。実例として、このプラグインには「タブが2枚未満なら一覧を隠す」という元仕様がありました。一覧がインライン表示だった時代には合理的な省スペース設計です。ところが私がドロワー化した後では、最後の1枚までタブを減らすとドロワーが強制的に閉じられ、開くボタンごと消えるという不可解な挙動に化けていました。

原因のコードを見つけて消すだけなら簡単です。でもその前に「なぜこの仕様が入ったのか」を考えると、単なる削除ではなく「ドロワー化した現在はこの前提が消えている。だから撤去してよい」という判断になります。改造とは元の設計者との対話で、意図を理解してから外した変更は、後から自分を裏切りません。

正本はどれか — 動いているバイナリから遡る

最後に、少し珍しいトラブルの話を。PC の移行作業でこのフォークのリポジトリが移行アーカイブの中に取り残され、「いま Obsidian で動いているプラグインの正しいソースはどれか」が分からなくなったことがありました。

このときの特定方法は、アーカイブ内のリポジトリをビルドし、その成果物と現に動いているプラグインファイルを md5 ハッシュで照合するというものです。完全一致したことで「これが正ソース」と確定し、リポジトリを所定の場所へ復帰させました。フォークは公式のリリース物と違って世界に1つしかないので、正本の特定手段を持っておくことは保険になります。

まとめ

変更は「万人に正しいか」で本家行きとフォーク行きに仕分ける
ソースと成果物を区別し、正本は常に git 側に置く
公式更新の上書きは防ぐのではなく、即復旧できる形で受け入れる
元仕様を消すときは、その仕様が入った理由を理解してから

oobe では、オープンソースのツールを業務に合わせて拡張・保守する支援も行っています。「便利だけど、うちの使い方には少し合わない」ツールをお使いの方は、お問い合わせからご相談ください。