release-pub

release-pub スキル

このスキルは、pub.dev に公開する Dart および Flutter パッケージ（Dart CLI ツールを含む）向けの、専用のリリースワークフローです。pubspec.yaml と CHANGELOG.md を安全に操作するため、ローカルのヘルパースクリプト（release_helper）を利用します。

公式ドキュメント

自動公開について詳しくは、Dart の公式ドキュメントを参照してください。 pub.dev へのパッケージの自動公開

注意

変更不可のタグ：すでに pub.dev に公開された Git タグを削除、変更、または再プッシュしてはいけません。pub.dev のエントリーは変更不可です。公開後に誤りが見つかった場合、既存のタグを上書きしようとせず、新しいバージョン（パッチリリースなど）を公開する必要があります。

ワークフローの概要

次の手順を正確に実行してください。

0. 初期設定の確認（初回のみ）

GitHub Actions 経由でパッケージを公開するのが初めての場合は、pub.dev で OIDC が設定され、ワークフローファイルが追加されていることを確認してください。

1. pub.dev を設定する：

   • https://pub.dev/packages/<package_name>/admin にアクセスするようユーザーに案内します。
   • Automated publishing セクションを見つけ、Enable publishing from GitHub Actions をクリックするよう案内します。
   • Repository は現在のリポジトリ（owner/repo）に設定することを推奨します。
   • Tag pattern を設定します。
     • 単一パッケージのリポジトリの場合：v{{version}}（推奨）または {{version}}。
     • モノレポの場合：package_name-v{{version}}。
   • セキュリティ強化（任意ですが推奨）：GitHub Deployment Environments を使用して、公開を特定のユーザー／承認者に制限する Require GitHub Actions environment オプションについて説明します。

2. GitHub Actions ワークフローを追加する：

   • .github/workflows/publish.yml に次の内容が含まれていることを確認します（必要に応じてタグパターンを調整してください）。

name: Publish to pub.dev

on:
  push:
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+*' # Align with the tag-pattern on pub.dev (e.g., 'v{{version}}')

jobs:
  publish:
    permissions:
      id-token: write # Essential for OIDC authentication
    uses: dart-lang/setup-dart/.github/workflows/publish.yml@v1
    # with:
    #   working-directory: path/to/package # Required if the package is not in the root

初回の自動リリースを進める前に、設定が完了したことをユーザーに確認してください。

1. リリース前のチェック

• 未コミットの変更がないか確認します：git status -s。変更がある場合は、続行する前にコミットまたはスタッシュするようユーザーに伝えてください。
• README／ドキュメントの更新確認：最近の変更を確認します。新機能や変更されたオプションがある場合、リリース前に README.md やその他のドキュメントを更新する必要がないか、ユーザーに確認を促します。
• 重要：プロジェクトの種類に応じて、適切なフォーマッター、アナライザー、テストを実行します。
  • Dart パッケージの場合：dart format .、dart analyze、dart test
  • Flutter パッケージの場合：flutter format .（または dart format .）、flutter analyze、flutter test
    • ［必須］：続行する前に、アナライザーの問題（エラー、警告、info レベルの lint を含む）をすべて解決します。避けられないことが明示的に文書化されている場合を除き、info レベルの問題を無視してはいけません。
    • 未解決の問題がある場合は、その内容を報告し、ユーザーに修正を依頼します（簡単なものであれば、修正を申し出ます）。
• 重要：公開前のドライランを実行します。
  • Dart パッケージの場合：dart pub publish --dry-run
  • Flutter パッケージの場合：flutter pub publish --dry-run 無視できることが想定されているものを除き、警告やエラーが表示された場合は、その内容を報告し、続行してよいかユーザーに確認します。

2. 変更を分析し、リリースを計画する

• 最新のタグを確認します：LAST_TAG=$(git tag --sort=-v:refname | head -1)
• 最新のタグ以降のコミットを分析します：git log ${LAST_TAG}..HEAD --oneline
• タグのプレフィックスが使われているか確認します：
  • $LAST_TAG の形式を確認します。v で始まる場合（例：v1.2.3）、新しいタグにも v をプレフィックスとして使用します。
  • タグが存在しない場合（初回リリース）は、v をプレフィックスとして使用します（TAG_PREFIX="v"）。
  • それ以外の場合は、既存の形式に従います（$LAST_TAG がバージョン文字列のみの場合はプレフィックスなし）。
• Conventional Commits に基づいて、バージョンの更新種別（major、minor、patch）を決定します：
  • BREAKING CHANGE: または <type>!: → major（ただし、バージョンが < 1.0.0 の場合は minor。1.0.0 未満での破壊的変更については、ユーザーの意向に従います）。
  • feat: → minor
  • fix:、docs:、chore:、refactor:、perf: など → patch
• 変更内容を説明する CHANGELOG.md 用の Markdown を生成します。変更メモはすべて 英語 で作成してください。スクリプトが自動で追加するため、変更メモに ## [version] - [date] のタイトル見出しを含めないでください。
• プレビューの生成（ドライラン）：ファイルを変更する前に、これから行うリリースの明確なプレビューをユーザーに提示します。
  • バージョン更新の推奨案（例：1.2.3 -> 1.3.0 (Recommended: feat=minor)）を示し、別の有効な SemVer の候補（例：1.2.4、2.0.0）も提示して、別の更新種別を選べるようにします。
  • リリースに含まれるコミットをカテゴリ別に一覧表示します。
  • これから追加する CHANGELOG.md のエントリーのプレビューを表示します。

3. ヘルパースクリプトを使った実行

同梱されている Dart CLI スクリプトを使って、安全に変更を適用します。スクリプトの場所は .agents/skills/release-pub/scripts/release_helper です。

1. リリースの準備（バージョン更新と変更履歴）： Step 2 で分析した更新種別（major、minor、patch）と変更メモを指定します。

   dart run .agents/skills/release-pub/scripts/release_helper/bin/release_helper.dart prepare <type> --notes "
   ### Features
   - ...
   
   ### Bug Fixes
   - ...
   "
   

2. 新しいバージョンの取得： pubspec.yaml を読み、新しく更新されたバージョン文字列（例：1.2.3）を確認します。これを $NEW_VERSION と呼びます。

4. ユーザーによる確認

Step 2 で生成したプレビューを基に、準備したリリース内容をユーザーに確認します：

• まず、バージョン変更の選択肢（例：「1.3.0（推奨）」、「1.2.4」、「2.0.0」）を提示します。
• ユーザーがバージョンを選んだら、Step 3 に従ってローカルのファイルを更新します。
• 実行ヘルパーの実行後、Git の差分（git diff）をユーザーに表示し、「リリースコミットとタグ（v$NEW_VERSION）を作成してよろしいですか？」と尋ねます。 明示的な確認を待ちます。

5. Git と GitHub の操作

ユーザーの確認後、次の操作を行います：

1. ファイルをステージングします：

   git add pubspec.yaml CHANGELOG.md
   

2. コミットします：

   git commit -m "chore: release v$NEW_VERSION"
   

   注：Co-Authored-By の行は追加しないでください。これはリリースコミットであり、コードへの貢献ではありません。
3. タグを付けます：

   git tag ${TAG_PREFIX}$NEW_VERSION
   

4. プッシュします：

   git push origin main
   git push origin ${TAG_PREFIX}$NEW_VERSION
   

5. GitHub リリースを作成します： 変更メモを一時ファイル（例：/tmp/release_notes.md）に保存してから、次を実行します：

   gh release create ${TAG_PREFIX}$NEW_VERSION --title "${TAG_PREFIX}$NEW_VERSION" --notes-file /tmp/release_notes.md
   env -u GITHUB_TOKEN -u GH_TOKEN gh release create ${TAG_PREFIX}$NEW_VERSION --title "${TAG_PREFIX}$NEW_VERSION" --notes-file /tmp/release_notes.md
   rm /tmp/release_notes.md
   

最後に、リリースが完了し、GitHub Actions が pub.dev へのプッシュを自動的に処理することを報告します。

6. pub.dev への公開を監視・確認する

リリースをプッシュした後も作業を続けてください。自動公開処理が完了するまで積極的に監視し、結果を速やかにユーザーに伝えてください。

1. ワークフローの実行を特定する： タグをプッシュした後、GitHub Actions が実行を登録するまで数秒かかります。GitHub CLI を使って、リリースコミットによってトリガーされた実行 ID を特定してください。

   COMMIT_SHA=$(git rev-parse HEAD)
   RUN_ID=""
   for i in {1..10}; do
     RUN_ID=$(env -u GITHUB_TOKEN -u GH_TOKEN gh run list --workflow=publish.yml -c "$COMMIT_SHA" --json databaseId -q '.[0].databaseId')
     if [ -n "$RUN_ID" ]; then
       break
     fi
     sleep 3
   done
   

   (--workflow=publish.yml で結果が得られない場合は、ワークフロー名またはファイル名が異なる可能性があるため、--workflow を指定せずに照会してください：env -u GITHUB_TOKEN -u GH_TOKEN gh run list -c "$COMMIT_SHA" --json databaseId,workflowName -q '.[0].databaseId'。)

2. ワークフローの進行状況を確認する： ワークフローの実行が完了するまで追跡してください。

   env -u GITHUB_TOKEN -u GH_TOKEN gh run watch "$RUN_ID" --exit-status
   

   • ワークフローが失敗した場合：エラーログをすぐに取得して、ユーザーに警告してください。

     env -u GITHUB_TOKEN -u GH_TOKEN gh run view "$RUN_ID" --log-failed
     

     何が失敗したのか（例：pub.dev の認証／OIDC、パッケージの検証エラー、環境の保護ルール）を説明し、解決方法を提案してください。

3. pub.dev でパッケージを確認する： ワークフローが成功したら、pub.dev で新しいバージョンが公開されていることを確認してください。

   PACKAGE_NAME=$(grep '^name:' pubspec.yaml | awk '{print $2}')
   for i in {1..10}; do
     STATUS=$(curl -s -o /dev/null -w "%{http_code}" "https://pub.dev/packages/$PACKAGE_NAME/versions/$NEW_VERSION")
     if [ "$STATUS" = "200" ]; then
       break
     fi
     sleep 3
   done
   

4. ユーザーに通知する： pub.dev でのリリースを確認できたらすぐに、公開が完了したことと pub.dev への直接リンクをユーザーに伝えてください。 "🎉 Successfully published $PACKAGE_NAME v$NEW_VERSION to pub.dev: https://pub.dev/packages/$PACKAGE_NAME/versions/$NEW_VERSION"

5. pub.dev のスコアを確認する（Pana 分析）： pub.dev は公開時に pana 分析を自動実行します。スコアを確認し、新しいバージョンの分析が完了するまで待ってください（通常は 1～3 分）。メトリクス API をポーリングします。 ヘルパースクリプトを使って pana 分析を監視し、スコアを確認してください。

   PACKAGE_NAME=$(grep '^name:' pubspec.yaml | awk '{print $2}')
   # Poll until the newly released version has been analyzed by pub.dev
   for i in {1..30}; do
     ANALYZED_VERSION=$(curl -s "https://pub.dev/api/packages/$PACKAGE_NAME/metrics" | jq -r '.scorecard.packageVersion // empty')
     if [ "$ANALYZED_VERSION" = "$NEW_VERSION" ]; then
       break
     fi
     sleep 10
   done
   dart run .agents/skills/release-pub/scripts/release_helper/bin/release_helper.dart check-score
   

   分析が完了したら、詳細なスコアを取得してください。

   SCORE_JSON=$(curl -s "https://pub.dev/api/packages/$PACKAGE_NAME/metrics")
   GRANTED_POINTS=$(echo "$SCORE_JSON" | jq -r '.score.grantedPoints')
   MAX_POINTS=$(echo "$SCORE_JSON" | jq -r '.score.maxPoints')
   

   (または、対象バージョンを明示的に指定します：dart run .agents/skills/release-pub/scripts/release_helper/bin/release_helper.dart check-score $NEW_VERSION)

   • 満点（$GRANTED_POINTS == $MAX_POINTS）の場合： すべてのセクションに合格し、タグ（is:wasm-ready など）が付与されていることを確認してください。
   • 減点されている場合（$GRANTED_POINTS < $MAX_POINTS）： 減点されたセクションと概要を抽出して表示してください。

     echo "$SCORE_JSON" | jq -r '.scorecard.panaReport.report.sections[] | select(.grantedPoints < .maxPoints) | "### \(.title) (\(.grantedPoints)/\(.maxPoints))\n\(.summary)\n"'
     

     速やかに対処できるよう、正確な減点内容をユーザーに知らせてください。 このコマンドは、$NEW_VERSION の分析が完了するまで pub.dev のメトリクスをポーリングします。次の内容が出力されます。
   • pub スコア（例：160 / 160）
   • WASM 互換性のステータス（is:wasm-ready）
   • プラットフォーム対応タグ
   • 正確な減点内容と概要（減点がある場合）
   • 減点がある場合は終了コード 1、満点の場合は終了コード 0

6. ユーザーに通知する： 公開の成功と pub.dev のスコアをユーザーに報告してください。 pub.dev へのリンクとともに、公開結果をユーザーに伝えてください。

   • pub.dev のバージョン：https://pub.dev/packages/$PACKAGE_NAME/versions/$NEW_VERSION
   • pub.dev のスコア：https://pub.dev/packages/$PACKAGE_NAME/score
   • スコア結果：
     • 満点の場合：例「🎉 Pub スコア：$GRANTED_POINTS / $MAX_POINTS（満点です！）」
     • 減点がある場合：例「⚠️ Pub スコア：$GRANTED_POINTS / $MAX_POINTS」と、減点の詳細な理由を伝えてください。
     • 減点がある場合：例「⚠️ Pub スコア：$GRANTED_POINTS / $MAX_POINTS」と、check-score が出力した減点の詳細な理由を伝えてください。