dart-package-maintenance

Dart パッケージのメンテナンス

Dart チームの正式な 外部パッケージのメンテナンス 仕様に沿って Dart パッケージをメンテナンスするためのガイドラインです。

このスキルを使用するタイミング

次のような場合にこのスキルを使用してください。

• Dart パッケージを更新する場合、リリースの準備をする場合、またはリポジトリ内で共同作業による変更を管理する場合。
• バージョン管理、CHANGELOG.md の同期、公開ワークフローを管理する場合。
• 公開するパッケージが Dart チームの規約に準拠していることを確認する場合。

使用しない場合（適用を控える基準）

次の場合は、パッケージのメンテナンスに伴うバージョンの更新や変更履歴の更新を行わないでください。

• 内部／プライベートパッケージ：pubspec.yaml で publish_to: none と指定され、pub.dev で公開されていないパッケージ（アプリケーションのルートパッケージや内部モノレポのツールなど）。
• リポジトリルートのファイルまたは過去の CHANGELOG.md の誤記：公開パッケージ以外のリポジトリレベルのファイル（.github/workflows/、リポジトリルートの SKILL.md、モノレポのルートドキュメントなど）のみを変更するプルリクエスト、または過去の CHANGELOG.md のセクションの誤記や書式のみを修正するプルリクエスト。
• 進行中のプルリクエストのコミット：バージョンに適切な -wip サフィックスがすでに付いている、アクティブな機能ブランチ上の中間コミット。

バージョン管理

セマンティックバージョニング

Dart パッケージでは、セマンティックバージョニングを使用します。ただし、1.0.0 のリリース前には変則的な方式を採用し、バージョン番号を右にずらします。詳細については、package:pub_semver のセマンティクスも参照してください。

• 1.0.0 以降のパッケージ：major.minor.patch。
• まだ 1.0.0 に達していないパッケージ：0.major.minor。2 番目の数値は、0.4.2 から 0.5.0-wip への更新のように、破壊的変更で増やします。3 番目の数値は、0.4.2 から 0.4.3-wip への更新のように、破壊的でない機能追加やバグ修正で増やします。+1 のビルドサフィックスは避けてください（package:pub_semver では、0.4.2+1-wip の +1-wip は -wip のプレリリースではなく、ビルドメタデータとして解析されます）。
• 推奨：パッケージが安定したら、できるだけ早く 1.0.0 をリリースすることを目指してください。

変更の影響に応じて、バージョンの更新幅を選択してください。

• メジャー：破壊的変更。pubspec.yaml の executables エントリの削除や名前変更を含みます。
• マイナー：新機能や、破壊的でない API の変更。新しいクラスの追加や、pubspec.yaml への executables エントリの追加などが該当します。
• パッチ：バグ修正、最小 environment.sdk 制約または実行時の dependencies 制約の更新、あるいは呼び出し側のコードに影響しないその他の変更。

バージョンの更新

リポジトリ内のコードが pub.dev で公開されている最新バージョンと異なる場合は、pubspec.yaml と CHANGELOG.md の両方で -wip バージョンを使用する必要があります。コードをその状態で公開する予定がない場合や、変更が利用者に影響しない場合でも、リリース後の 最初の 変更時に -wip に更新します。

プルリクエストを作成またはマージする際は、pubspec.yaml と CHANGELOG.md の現在のバージョンを確認してください。

• 現在のバージョンが公開済みの場合（例：1.2.3）：適切なバージョン更新を行い、pubspec.yaml に -wip を追加して、CHANGELOG.md の先頭に対応する ## <version>-wip セクションを追加します。
• すでに -wip バージョンの場合（例：1.2.4-wip）：既存の -wip の更新幅と、今回の変更に必要な更新幅を比較します。機能追加により パッチ から マイナー への更新が必要になるなど、今回の変更により大きな更新が必要な場合は、pubspec.yaml を更新し、CHANGELOG.md の既存の ## <version>-wip 見出しをその場で変更します。
• まだ pub.dev に公開されておらず、0.1.0-wip の場合：初回リリース後までは 0.1.0-wip と - Initial release. のエントリを維持し、プルリクエストごとの変更履歴エントリを追加しないでください。

CHANGELOG.md の更新

• ユーザーに見える変更：先頭の -wip セクションにエントリーを追加します。
• 内部的な変更またはユーザーに見えない変更（安全なリファクタリング、リンターのクリーンアップ、test/、tool/、README.md の更新、dev_dependencies や dependency_overrides の変更など）：
  • PR で新しい -wip セクションを作成する場合は、その下に箇条書き項目を追加せず、## <version>-wip の見出しを追加します。
  • パッケージがすでに -wip バージョンの場合は、CHANGELOG.md に手を加えず、PR に skip-changelog-check ラベルを適用します。
• 未リリースの変更への追加修正：後続の PR で、公開前に SDK や依存関係の制約を再度引き上げる場合など、現在の -wip セクションにある未リリースの変更を修正または取り消す場合は、重複するエントリーを追加せず、既存の -wip の箇条書き項目をその場で更新または削除します。
• 公開済みのセクション：すでに公開されているバージョンの見出しの下には、新しいエントリーを追加しないでください。PR の作業中にリリースが行われた場合など、main のマージ後は特に注意してください。

破壊的変更

• 依存パッケージや内部プロジェクトへの影響を評価します。
• 可能であれば、変更を内部の presubmit でテストすることを検討してください。
• 下流での破損を最小限に抑えるため、段階的なロールアウトを優先します（例：新しい動作をオプトイン方式にします）。

公開プロセス

1. 準備：専用のプルリクエストで pubspec.yaml と CHANGELOG.md から -wip サフィックスを削除します。
2. 実行：dart pub publish（または flutter pub publish）を実行し、すべての警告とエラーを解消します。
3. タグ付け：公開したバージョンの git タグを作成してプッシュします。
   • 単一パッケージのリポジトリ：v1.2.3
   • モノレポ：package_name-v1.2.3
   • 例：git tag v1.2.3 && git push --tags

プルリクエストの管理

• コミット：各 PR は通常、マージ時に単一のスカッシュコミットにします。
• 履歴の共有：PR を作成した後は、ブランチへの強制プッシュを避けてください。
• 競合の解決：競合を解決する際は、リベースではなく、PR ブランチに main をマージする方法を優先してください。これにより、レビューの履歴とコメントが保持されます。
• レビュー：「Files changed」ビューからコメントを追加し、まとめて送信します。
• ローカルでの確認：gh pr checkout <number> を使って、IDE で変更を確認します。