GitHub releases の使用を検討 - ブランチアーカイブからの移行

[toshi0806]

概要

現在、aldc は latex-environment をダウンロードする際に以下の形式でブランチアーカイブを使用しています：

${REPOSITORY_URL}/archive/refs/heads/${BRANCH}.zip

この方法について、GitHub releases の使用を検討することを提案します。

現在の実装の課題

ブランチアーカイブ方式の問題点

1. バージョン管理の不安定性

   • ブランチの内容が予告なく変更される可能性
   • 特定の時点での状態を保証できない
   • 再現可能性の問題

2. 依存関係管理の困難さ

   • 明確なバージョン番号がない
   • 互換性の確認が困難
   • 破壊的変更の通知が困難

3. ユーザーエクスペリエンスの問題

   • どのバージョンを使用しているか不明
   • 安定版と開発版の区別ができない
   • 問題発生時のトラブルシューティングが困難

GitHub Releases を使用する利点

1. バージョン管理の改善

• セマンティックバージョニング: v1.0.0, v1.1.0 などの明確なバージョン番号
• 安定性: リリース後の内容は変更されない
• タグベース: 特定のコミットに対応する確実な参照

2. 依存関係管理の向上

• 互換性マトリクス: どのバージョンが互換性があるか明確
• 破壊的変更の通知: メジャーバージョンアップで明示
• 段階的アップグレード: マイナーバージョンでの安全な更新

3. ユーザーエクスペリエンスの改善

• 明確な選択肢: 安定版、プレリリース版の区別
• リリースノート: 変更内容の詳細な説明
• ダウンロード統計: 利用状況の把握

技術的実装方法

GitHub Releases API の活用

# 最新リリースの取得
curl -s https://api.github.com/repos/smkwlab/latex-environment/releases/latest

# 特定バージョンの取得
curl -s https://api.github.com/repos/smkwlab/latex-environment/releases/tags/v1.0.0

ダウンロード URL の変更

# 現在の方式
${REPOSITORY_URL}/archive/refs/heads/${BRANCH}.zip

# 提案する方式
${REPOSITORY_URL}/archive/refs/tags/${VERSION}.zip
# または
${REPOSITORY_URL}/releases/download/${VERSION}/latex-environment-${VERSION}.zip

実装上の検討事項

1. バージョン指定方法

• デフォルト動作: 最新安定版を使用
• 明示的指定: --version v1.2.0 のようなオプション
• プレリリース: --pre-release フラグでベータ版を使用

2. 下位互換性

• 既存のブランチ指定方式も維持
• 段階的な移行をサポート
• 移行期間中の警告メッセージ

3. エラーハンドリング

• 指定されたバージョンが存在しない場合の処理
• ネットワークエラー時のフォールバック
• 不正なバージョン形式の検証

影響範囲

latex-environment リポジトリ

• GitHub Actions でのリリース自動化
• バージョンタグの適切な付与
• リリースノートの作成

aldc の変更点

• バージョン解決ロジックの実装
• CLI オプションの追加
• エラーメッセージの改善

エコシステム全体

• 他のコンポーネントとの整合性確保
• ドキュメントの更新
• ユーザー向けの移行ガイド

提案する実装手順

1. Phase 1: GitHub Releases API 対応の実装
2. Phase 2: CLI オプションの追加とテスト
3. Phase 3: デフォルト動作の変更
4. Phase 4: 旧方式の廃止予定告知

関連Issue・PR

• latex-environment リポジトリでのリリース自動化
• ecosystem-manager.sh での対応
• ドキュメントの更新

この変更により、より安定で管理しやすいバージョン管理システムを構築できると考えています。ご検討をお願いします。

[toshi0806]

調査結果：現時点では実装を見送り、latex-environment 側のリリース体制整備が前提

本 Issue の提案について aldc 側と latex-environment 側の現状を調査した。結論として、現時点での aldc コード変更は時期尚早であり、latex-environment 側のリリース体制整備が先行課題である。以下に根拠と推奨ロードマップを記録する。

1. 現状の aldc 実装

aldc は固定で release ブランチのアーカイブを取得している（aldc:4-20）。

BRANCH='release'
TARGET=${REPOSITORY_URL}/archive/refs/heads/${BRANCH}.zip

release ブランチが latex-environment の「安定チャネル」として機能している。

2. latex-environment 側のリリースの実態（重要）

GitHub Releases API で確認したところ、セマンティックバージョニングのリリース（v1.0.0 等）は存在しなかった。

• 既存の release はすべて prerelease: true
• タグ名はブランチ名ベースの自動生成（例: issue-92-actionlint-improvements-release, update-to-v3.1.0-release）
• 実体は LaTeX Release Action による PDF ビルド成果物であり、devcontainer テンプレートのバージョン付きリリースではない
• releases/latest 相当の安定版が無い（最新 release が feature ブランチの prerelease になる）

ブランチは main / release / 作業中ブランチのみで、バージョンタグ運用は行われていない。

3. 結論

本 Issue が前提とする「GitHub Releases + セマンティックバージョニング」へ aldc を単純移行すると、現状では以下の問題が発生する。

• releases/latest を参照しても安定版が取得できない（prerelease が返る／PDF 成果物が混在）
• バージョン指定の参照先となるセマンティックタグが存在しない

したがって latex-environment 側のリリース体制整備（Phase 0）が未完了の段階で aldc を変更しても意味が無い。

4. 推奨ロードマップ（順序の見直し）

Issue 本文の Phase 1〜4 の前に、latex-environment 側の整備を先行課題として追加する。

• Phase 0（前提・latex-environment 側）: セマンティックバージョニングのリリース自動化を整備
  • release ブランチへのマージ時に vX.Y.Z タグと安定版 Release（prerelease: false）を発行
  • LaTeX Release Action による PDF 成果物リリースと、テンプレート配布用リリースを分離 or 識別可能にする
  • リリースノート（変更内容・破壊的変更）の運用ルール策定
• Phase 1（aldc）: 安定版 Release が出揃った段階で、バージョン解決ロジックを実装
• Phase 2（aldc）: --version / --pre-release CLI オプション追加、release ブランチ方式との後方互換維持
• Phase 3（aldc）: デフォルト動作を最新安定版参照へ変更
• Phase 4: 旧方式の廃止予定告知・移行ガイド

5. 当面の対応

• aldc のコード変更は本 Issue では行わない
• 本 Issue は latex-environment 側のリリース自動化（Phase 0）の完了を待つステータスとする
• Phase 0 完了後、aldc 側の実装（Phase 1 以降）を別 Issue または本 Issue 再開で着手する

補足: aldc の --version 対応自体は archive/refs/tags/${VERSION}.zip と archive/refs/heads/${BRANCH}.zip を切り替えるだけなので技術的には軽量に先行実装も可能だが、参照先のタグが存在しない以上、ユーザー価値が無いため見送る判断とした。

[toshi0806]

前提課題（Phase 0）として latex-environment 側に Issue を作成した: smkwlab/latex-environment#144

本 Issue（aldc の Phase 1 以降）は、latex-environment#144 の完了を待って再開する。