古い Polaris リファレンスは 「直近4バージョン」だけ公開へ
原題: Removing outdated Polaris reference docs
- Polaris
- UI Extensions
- Checkout
- Customer Accounts
- POS
- GraphQL
- CLI
- API Versioning
- Documentation
- 仕様変更
図解 : 古い Polaris リファレンスドキュメントの公開終了(直近4バージョンのみ公開へ) Developer Changelog / ドキュメント方針 古い Polaris リファレンスは 「直近4バージョン」だけ公開へ Polaris のリファレンスドキュメントが Shopify の GraphQL API と同じバージョン管理ポリシーに統一。各 stable バージョンは最低 12 か月サポートされ、2026-04 リリース以降は直近 4 つの stable バージョンだけが Shopify.dev に掲載される。古いバージョンの拡張は動き続けるが、専用ドキュメントは消える。 このページの構成 そもそも何が変わるのか(30秒で理解) 仕組み図解 : バージョンとドキュメント公開範囲 対象になる4つの UI 拡張ドキュメント 従来 vs 新ポリシーの比較 影響を受けるケース/受けないケース エンジニアが取るべきアクション(3ステップ) 技術者が押さえるべき5つのポイント 業務に活かせる3つのユースケース 提案で使える1行サマリ 1 そもそも何が変わるのか Polaris のリファレンスドキュメントが、 Shopify の GraphQL API と同じバージョン管理ポリシー に統一された。 各 stable バージョンは 最低 12 か月サポート 。 2026-04 リリース以降、Shopify.dev に載るのは直近 4 つの stable バージョンのドキュメントだけ になる。 従来 : 全バージョンの docs が掲載 古い stable バージョンのリファレンスも Shopify.dev に残り続けていた。 新ポリシー : 直近4バージョンのみ 最低 12 か月サポート+直近 4 stable バージョンだけを公開。それより古いものは docs から外れる。 重要 : 「ドキュメントが消える」だけで「動かなくなる」わけではない。 記事は「Older versions continue to work(古いバージョンも動作は継続する)」と明記。なくなるのは Shopify.dev 上の専用リファレンスのみ。 2 仕組み図解 : バージョンとドキュメント公開範囲 ドキュメント消失とデプロイ可否は連動した設計。 Shopify CLI は すでに 12 か月より古い API バージョンを狙ったデプロイをブロックしている。つまり「docs が消えた頃にはデプロイもできない」状態に揃う。Shopify は「サポート対象バージョンに保つこと」を推奨。 ※ 公開対象を「直近4バージョン」とする記事の表現と、「各 stable バージョンは最低12か月サポート」という方針は対応している(Shopify の GraphQL API と同一ポリシー、と記事は述べている)。古い docs が即時削除されるのか段階的かといった具体的タイミングは記事に記載なし。 3 対象になる4つの UI 拡張ドキュメント 記事が「直近4 stable バージョンのみ公開」と明記しているリファレンスは次の4種類。 Admin UI extensions 管理画面の拡張 Checkout UI extensions チェックアウトの拡張 Customer account UI extensions アカウント画面の拡張 POS UI extensions POS(実店舗)の拡張 4 従来 vs 新ポリシーの比較 項目 従来 新ポリシー(2026-04〜) ドキュメント公開範囲 広い 古いバージョンの docs も残存 直近4 last 4 stable versions のみ バージョン管理ポリシー 個別 統一 GraphQL API と同じ サポート期間 明示の記載なし 最低12か月 各 stable バージョン 古いバージョンの動作 動く 動く(docs だけが消える) 12か月超のデプロイ 不可 Shopify CLI が すでに ブロック済み(今回の変更前から) 5 影響を受けるケース/受けないケース 影響あり 古いバージョンに固定された拡張を保守中 12か月より古い stable バージョンを参照していると、近い将来ドキュメントが Shopify.dev から消え、リファレンスを引けなくなる。さらに CLI が既にその先へのデプロイをブロックしている。 影響あり 古い docs URL を社内資料に貼っている 直近4バージョン外のリファレンス URL は、いずれ参照不能になる可能性。ブックマーク/Wiki のリンク切れリスク。(削除の具体的タイミングは記事に記載なし) 影響なし サポート対象バージョンで運用中 直近4 stable バージョン(≒最低12か月以内)で拡張を維持していれば、ドキュメントもデプロイも従来どおり。 影響なし 稼働中の古い拡張そのもの 「Older versions continue to work」とあるとおり、古いバージョンの拡張の 動作 は止まらない。今回はあくまでドキュメント公開範囲の話。 6 エンジニアが取るべきアクション(3ステップ) 1 拡張のターゲットバージョンを棚卸し 各拡張(Admin / Checkout / Customer account / POS)が参照している API バージョンを一覧化。 2 12か月以内のサポート対象へ更新 直近4 stable バージョン内に収まるようバージョンを引き上げる。記事もこれを推奨。 3 定期更新を運用に組み込む 四半期ごとのバージョン確認をカレンダー/CI に組み込み、docs 消失とデプロイブロックを未然に回避。 Shopify CLI が 12か月超のデプロイを すでに 止めてくれているので、CLI でデプロイが通る=サポート対象内、と捉えると判断が早い。 7 技術者が押さえるべき5つのポイント 1. GraphQL API と同一ポリシー Polaris reference docs が Shopify の GraphQL API と同じバージョン管理ポリシーに統一。各 stable バージョンは最低12か月サポート。API と拡張のバージョン管理を同じ尺度で考えられる。 2. 動作は止まらない 消えるのは Shopify.dev 上の 専用ドキュメントだけ 。古いバージョンの拡張自体は引き続き動作する(後方互換は維持)。 3. CLI のブロックは導入済み Shopify CLI は 12か月より古い API バージョンへのデプロイを すでに 防いでいる。今回の docs 変更で新たに何かが壊れるわけではなく、方針が明文化された形。 4. 公開は「直近4 stable バージョン」 2026-04 リリース以降、掲載されるのは last four stable versions のみ。サポート期間(最低12か月)と整合する範囲、と理解しておく。 5. 対象は4種の UI 拡張ドキュメント Admin UI / Checkout UI / Customer account UI / POS UI extensions の各リファレンスが対象。複数種を併用するプロジェクトでは、それぞれのバージョン追従を別々に管理する必要がある。 古い docs URL を社内資料に貼っている場合はリンク切れに注意 (削除の具体的タイミングは記事に記載なし)。 8 業務に活かせる3つのユースケース USE CASE 1 制作会社の「拡張バージョン追従」を運用ルール化 課題 複数クライアントの拡張を保守しており、案件ごとにターゲット API バージョンがバラバラ。古いものはいずれドキュメントが消え、保守時に仕様を引けなくなる。 打ち手 全拡張のターゲットバージョンを棚卸しし、直近4 stable バージョン(≒12か月以内)に揃える定期メンテ枠を設定。 効果 ドキュメント参照可能な状態を維持しつつ、CLI のデプロイブロックも回避。保守工数の見積りが安定する。 技術メモ Shopify CLI が 12か月超のデプロイを既にブロックしているため、「デプロイが通るか」がサポート対象内の簡易チェックになる。 USE CASE 2 社内ナレッジ/ブックマークのリンク切れ対策 課題 チームの Wiki や手順書に、特定バージョンの Polaris/UI 拡張ドキュメント URL を貼っている。古いバージョンの docs が公開対象外になると 404 リスク。 打ち手 参照リンクを最新(バージョン非依存)の docs に張り替え、ナレッジに「掲載は直近4 stable バージョンのみ」という前提を明記。 効果 リンク切れ・古い仕様の参照を防止。新人オンボーディング資料の鮮度を保てる。 技術メモ 古い docs の削除タイミングの詳細は記事に記載なし。先回りでリンク棚卸しをしておくのが安全。 USE CASE 3 長期運用ストアのアップグレード計画に組み込む 課題 リプレイス後や長期運用のストアで拡張のバージョンが古いまま固定。放置するとドキュメント消失+将来のデプロイブロックに直面。 打ち手 四半期ごとの API/拡張バージョン棚卸しを運用カレンダー・CI に組み込み、サポート窓(直近4バージョン)から外れる前に更新。 効果 計画的アップグレードで「気づいたら docs もデプロイも詰んでいた」を回避。リスクの見える化。 技術メモ GraphQL API と同じ versioning policy なので、API バージョンと UI 拡張バージョンの管理サイクルを一本化できる。 9 提案で使える1行サマリ 「Polaris の UI 拡張ドキュメントは GraphQL API と同じ 最低12か月サポート・直近4 stable バージョンのみ公開 に統一。 古い拡張は動き続けるが ドキュメントは消える ので、拡張は 12か月以内のサポート対象バージョンに保つ のが安全。 CLI が既に古いバージョンへのデプロイを止めているため、定期的なバージョン追従を運用ルール化しておけばよい。」 source : shopify.dev / changelog / removing-outdated-polaris-reference-docs 公開日 : 2026-04-01(Developer Changelog)