背景
テーマやプラグインの開発者は、通常、Discourse の latest リリースを対象に開発し、後方互換性の心配を避けたいと考えています。しかし、古い Discourse リリースを実行しているサイトには、それに対応するテーマ/プラグインのバージョンが必要です。
このギャップを埋めるために、Discourse には、テーマ/プラグインの古い「ピン留め」バージョンをチェックアウトするよう指示することができます。これには2つの仕組みがあり、以下の順序でチェックされます：
- テーマ/プラグインのリポジトリにある
d-compat/<YYYY>.<M>git ブランチ（主要な方法 — 新規のピン留めにはすべて推奨）。 - リポジトリのルートにある
.discourse-compatibilityYAML ファイル（元の仕組み、フォールバックとして引き続きサポート）。
両方が存在する場合、ブランチが優先されます。
d-compat/<YYYY>.<M> ブランチシステム
Discourse のリリースは 2025.5、2025.6 のような日付ベースのバージョンを使用します。Discourse が git からプラグインやテーマを更新する際、リポジトリに対して「自分のバージョンに一致する d-compat/<YYYY>.<M> という名前のブランチはありますか？」と問いかけます（例：Discourse 2025.5.x には d-compat/2025.5）。該当するブランチがある場合、Discourse は main の代わりにそのブランチの先端をチェックアウトします。
この検索は、ローカルでのチェックアウトがリポジトリの デフォルトブランチ にある場合のみ実行されます。意図的に他のブランチにピン留めしている場合、d-compat ロジックはスキップされ、あなたのピン留めが尊重されます。
このシステムで古い Discourse バージョンをサポートするには：
- そのバージョンで動作することが確認されているコミットから、
d-compat/<YYYY>.<M>という名前のブランチを作成します（例：git checkout -b d-compat/2025.5 <commit>）。 originにプッシュします。誤って削除されないよう、ブランチを保護することを検討してください。- バックポートコミットをそのブランチにマージします。
2025.5.xの Discourse インスタンスは次の更新時にそれらを自動的に取得し、新しい Discourse のインスタンスはデフォルトブランチを継続して追跡します。
ブランチを使用する場合、.discourse-compatibility を変更する必要はありません。
自動ブランチ作成（create-d-compat-branch.yml）
実際には、これらのブランチを手動で作成する必要はほとんどありません。デフォルトのテーマやプラグインのスケルトンには、毎日実行され、Discore コアの新バージョンをチェックし、必要に応じて対応する d-compat/<YYYY>.<M> ブランチをプッシュする d-compat-branch.yml ワークフロー が含まれています。
リポジトリがスケルトンの古いコピーから作成された場合、d-compat-branch.yml ファイルを .github/workflows ディレクトリにコピーするだけで動作します。
d-compat ブランチへの修正のバックポート
デフォルトブランチにマージした修正が、古い Discourse リリースのサイトにも届く必要がある場合：
-
対象の d-compat ブランチから分岐し、修正をチェリーピックします：
git fetch origin git checkout -b backport/my-fix-2025.5 origin/d-compat/2025.5 git cherry-pick <commit-sha> git push -u origin backport/my-fix-2025.5 -
ベースブランチ を
d-compat/2025.5に設定して PR を作成します（mainではありません）。他の PR と同じようにレビューとマージを行います。 -
修正が必要な各古い
d-compat/<YYYY>.<M>ブランチに対して繰り返します。
2025.5.x のサイトは、次の更新時にマージされたコミットを取得します。
レガシーフォールバック：`.discourse-compatibility` ファイル
対応する d-compat ブランチが存在しない場合、Discourse はリポジトリのルートにある YAML の .discourse-compatibility ファイルにフォールバックし、Discourse バージョンをプラグイン/テーマの git リファレンスにマッピングします：
< 3.2.0.beta2-dev: abcde
Discourse は、実行中のコアバージョンに一致する最も低いエントリを選択するため、< 3.2.0.beta2-dev のユーザーはコミット abcde をチェックアウトします。バージョンの境界を指定するには <（または、オペレーターが指定されていない場合のデフォルトであるレガシーの <=）を使用します。これは、ブランチベースのシステムでは必要とされることを表現できない場合のみ使用してください。
このドキュメントはバージョン管理されています - 変更提案は github でお願いします。