speee版 jsonapi-resources の配布方法の提案とバージョン戦略

[takaokouji]

背景

upstream (cerebris/jsonapi-resources) の開発が停止しており、Rails バージョンアップの際にこの gem を更新できず、ブロッカーになっています。

現状:

• dx-nurikae などの複数プロダクトが jsonapi-resources v0.9.12 に依存
• Rails 7.1+ / 8.0+ への対応が必要
• speee/jsonapi-resources で対応を進めているが、配布方法が未確定

調査結果

GitHub Packages の制約

GitHub Packages の RubyGems registry では、public packages でも Personal Access Token による認証が必須という制約があります。

参考:

• Working with the RubyGems registry - GitHub Docs
• Why Do We Need to Authenticate to Download/Read Ruby Gems?

この制約により、GitHub Packages を public gem registry として使用することは実用的ではありません。

提案する配布方法

案1: GitHub 直接参照（推奨）

Gemfile での記載:

gem 'jsonapi-resources', github: 'speee/jsonapi-resources', tag: 'v26.1.0'

メリット:

• ✅ 認証不要で誰でもインストール可能
• ✅ インフラ不要、即座に導入可能
• ✅ タグでバージョン管理が明確
• ✅ Bundler が自動的にキャッシュ（2回目以降は高速）

デメリット:

• ⚠️ 初回インストール時に git clone が発生
• ⚠️ 通常の gem より若干インストールが遅い

実装の容易さ: ★★★★★

---

案2: RubyGems.org への公開

Gemfile での記載:

gem 'jsonapi-resources-speee', '~> 26.1'

メリット:

• ✅ 完全に認証不要
• ✅ bundle install が高速
• ✅ 標準的な gem 配布方法
• ✅ バージョン管理が明確

デメリット:

• ⚠️ gem 名を変更する必要がある（例: jsonapi-resources-speee）
• ⚠️ 既存コードの gem 'jsonapi-resources' を書き換える必要
• ⚠️ RubyGems.org のアカウント管理が必要
• ⚠️ 元の jsonapi-resources と名前空間が競合する可能性

実装の容易さ: ★★★☆☆

必要な作業:

• gemspec の name, homepage, authors を更新
• README に upstream との関係を明記
• RubyGems.org へのアカウント登録と権限管理

---

案3: 独自 Gem Server（Gemstash/Geminabox）

社内 gem server を構築し、そこから配布。

Gemfile での記載:

source 'http://gems.speee.jp' do
  gem 'jsonapi-resources', '~> 26.1'
end

メリット:

• ✅ 複数のプライベート gem を統一管理可能
• ✅ rubygems.org のキャッシュプロキシとしても機能
• ✅ gem 名の変更不要

デメリット:

• ❌ サーバーの構築と運用が必要
• ❌ インフラコスト（サーバー、ドメイン、SSL証明書）
• ❌ 小規模チームには過剰な仕組み

実装の容易さ: ★☆☆☆☆

---

バージョニング戦略: 26.1.0

提案: カレンダーバージョニング + セマンティックバージョニングのハイブリッド

• メジャーバージョン: 26（2026年）
• マイナーバージョン: 1（1月または機能追加）
• パッチバージョン: 0（初回リリース）

利点:

1. upstream との競合回避

   • 現在の upstream: 0.11.0.beta1（最新リリース: 0.9.12）
   • 26.x.x は upstream が使用する可能性がほぼゼロ

2. 明確な管理

   • 26.1.1, 26.1.2 でバグフィックス
   • 26.2.0 で機能追加
   • 27.1.0 で2027年版

3. 依存関係の指定が容易

   gem 'jsonapi-resources', '~> 26.1'  # 26.1.x のみ
   gem 'jsonapi-resources', '>= 26.1', '< 27'  # 26.x.x を許可

---

推奨アプローチ

即座に導入: 案1（GitHub 直接参照）

# dx-nurikae/Gemfile
gem 'jsonapi-resources', github: 'speee/jsonapi-resources', tag: 'v26.1.0'

理由:

• インフラ不要で即座に導入可能
• 認証不要で全メンバーが使用可能
• Bundler のキャッシュにより実用上のパフォーマンス問題なし

将来的な検討: 案2（RubyGems.org への公開）

複数プロダクトでの採用が増えた場合、または他の OSS プロジェクトへの貢献を考慮する場合に検討。

---

実装計画（案1を採用する場合）

• lib/jsonapi/resources/version.rb を 26.1.0 に更新
• CHANGELOG.md を作成/更新（speee版の変更履歴を記載）
• README.md に speee 版についての説明を追加
  • upstream との関係
  • インストール方法
  • バージョニング戦略
• Git タグ v26.1.0 を作成し push
• dx-nurikae で動作確認
  • Gemfile を更新
  • bundle install
  • テスト実行
• 他のプロダクトへの展開手順をドキュメント化

---

議論ポイント

1. 案1（GitHub直接参照）で問題ないか？

   • インストール速度は許容範囲か？
   • CI/CD での動作に問題はないか？

2. バージョン 26.1.0 で良いか？

   • 他の命名規則の提案はあるか？

3. 将来的に RubyGems.org への公開を検討すべきか？

   • gem 名の変更（jsonapi-resources-speee）は許容できるか？

4. CHANGELOG や README の内容

   • upstream との違いをどこまで明記するか？
   • メンテナンス方針をどう記載するか？

[takaokouji]

We have decided to distribute this fork via GitHub repository references.

To use the speee fork, add the following to your Gemfile:

gem 'jsonapi-resources', github: 'speee/jsonapi-resources', tag: 'v26.1.1'

This approach was chosen for simplicity. The README.md has been updated to reflect this installation method.

Available tags can be found at: https://github.com/speee/jsonapi-resources/tags