古いDiscourseインストール向けのプラグインとテーマのバージョン固定（d-compatブランチ）

ドキュメント 開発者ガイド
1

:open_book: 背景

テーマおよびプラグイン開発者は、後方互換性を気にすることなく、Discourse の latest リリースをターゲットにしたいと考えています。しかし、古い Discourse リリースを実行しているサイトでは、それでも動作するテーマ/プラグインのバージョンが必要です。

このギャップを埋めるために、Discourse にはテーマ/プラグインの古い「ピン留め」されたバージョンをチェックアウトするよう指示できます。これには、以下の 2 つのメカニズムがあり、順序通りにチェックされます。

  1. テーマ/プラグインリポジトリ内の d-compat/<YYYY>.<M> git ブランチ（主要なメカニズム — すべての新しいピン留めに推奨）。
  2. リポジトリのルートにある .discourse-compatibility YAML ファイル（元のメカニズム。フォールバックとして引き続きサポートされています）。

両方が存在する場合は、ブランチが優先されます。

:herb: 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 バージョンをサポートするには、以下の手順を行います。

  1. そのバージョンで動作することが知られているコミットから d-compat/<YYYY>.<M> という名前のブランチを作成します（例：git checkout -b d-compat/2025.5 <commit>）。
  2. それを origin にプッシュします。誤って削除されないようにブランチを保護することをお勧めします。
  3. 必要なバックポートコミットをそのブランチにマージします。2025.5.x の Discourse インスタンスは、次の更新時に自動的にそれらを取得します。新しい Discourse を実行しているインスタンスは、デフォルトブランチの追跡を継続します。

ブランチを使用する場合は、.discourse-compatibility を一切操作する必要はありません。

:gear: 自動ブランチ作成 (create-d-compat-branch.yml)

実際には、これらのブランチを手動で作成する必要はほとんどありません。デフォルトのテーマおよびプラグインのスケルトンには、d-compat-branch.yml ワークフロー が含まれており、これは毎日実行され、Discourse コアの新しいバージョンをチェックし、必要に応じて一致する d-compat/<YYYY>.<M> ブランチをプッシュします。

リポジトリがスケルトンの古いコピーから作成された場合は、d-compat-branch.yml ファイルを .github/workflows ディレクトリにコピーするだけで動作します。

:git_merged: d-compat ブランチへの修正のバックポート

デフォルトブランチに修正をマージした後、その修正を古い Discourse リリースを実行しているサイトにも届ける必要がある場合：

  1. 対象の d-compat ブランチからブランチを作成し、修正をチerryピックします。

    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

  2. ベースブランチを d-compat/2025.5（main ではありません）として PR を開きます。他の PR と同様にレビューとマージを行います。

  3. 修正が必要な古い 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 で変更を提案してください。

「いいね！」 17
From Discourse 3.2: adding -dev suffix to beta versions under active development
Introducing .discourse-compatibility: pinned plugin/theme versions for older Discourse versions
Trading Buttons
Links not appearing since the last theme component update
What is the purpose of the compatibility entry in the theme skeleton?
Upcoming post menu changes - How to prepare themes and plugins
Give Plugin versions for minimum and maximum discourse version
Theme component update always installs old version (via rake or manually) (solved)
Mint Theme
Visiting /admin/upgrade may lead to a server error
Category Icons
4

バージョンが 3.5.0.beta8-dev より小さい場合、3.5.0 は含まれますか？

5

No. 3.5.0 は、リリース候補版の「3.5.0.beta8-dev」よりも「大きい」と見なされます。

常に Ruby コンソールで比較を試すことができます。

> Gem::Version.new("3.5.0") < Gem::Version.new("3.5.0.beta8-dev")
=> false
「いいね！」 5
6

承知いたしました。説明ありがとうございます！

「いいね！」 1
7

このドキュメントは、Discourse の新しいバージョン管理戦略に関する RFC（https://meta.discourse.org/t/rfc-a-new-versioning-strategy-for-discourse/383536）で説明されている新しい d-compat/* 戦略について更新されました。この戦略は現在、利用可能です。

「いいね！」 2