パッケージの公開

pub パッケージマネージャーは、他者のパッケージを使用するためだけではありません。自身のパッケージを世界と共有することもできます。有用なプロジェクトがあり、他者に利用してもらいたい場合は、dart pub publish コマンドを使用します。

パッケージのビルドと公開の概要については、次のビデオをご覧ください。

公開されたパッケージは永続的であることを忘れないでください。パッケージを公開するとすぐに、ユーザーはそのパッケージに依存できるようになります。一度依存し始めると、パッケージを削除するとそれらのパッケージが壊れてしまいます。これを避けるため、pub.dev ポリシーでは、ごく一部の例外を除き、パッケージの非公開化は禁止されています。

パッケージの新しいバージョンはいつでもアップロードできますが、古いバージョンはまだアップグレードできないユーザーのために利用可能なままです。

関連性が失われた、またはメンテナンスが不足している公開済みパッケージについては、提供停止としてマークしてください。

パッケージを公開する際は、pubspec フォーマットとパッケージレイアウト構造にある規約に従ってください。パッケージの使いやすさを簡素化するために、Dart はこれらの規約を要求します。これらの規約には、リンクされたガイドに記載されている例外がいくつかあります。pub は、Dart エコシステム内でパッケージがよりうまく機能するように、どのような変更が可能かを示します。

これらの規約以外にも、以下の要件を満たす必要があります。

• パッケージに LICENSE ファイルを含めてください。Dart および Flutter チームが一般的に使用する BSD 3条項ライセンスをお勧めします。ただし、パッケージに適したライセンスであればどのようなものでも使用できます。

• パッケージの一部としてアップロードするすべてのものの再配布に関する法的権利があることを確認してください。

• パッケージサイズを gzip 圧縮後 100 MB 未満に保ってください。サイズが大きすぎる場合は、複数のパッケージに分割する、.pubignore ファイルを使用して不要なコンテンツを削除する、または含めるリソースや例の数を減らすことを検討してください。

• パッケージの依存関係は、デフォルトの pub パッケージサーバーからのホスト済み依存関係と SDK 依存関係 (sdk: flutter) のみにしてください。これらの制約により、パッケージの依存関係を将来見つけ、アクセスできるようになります。

• Google アカウントを所有してください。pub は Google アカウントを使用してパッケージアップロード権限を管理します。Google アカウントは、Gmail アドレスまたはその他のメールアドレスに関連付けることができます。

pub は、いくつかのファイルのコンテンツを使用して、pub.dev/packages/<your_package> にパッケージのページを作成します。以下のファイルがパッケージの Web ページのコンテンツに影響します。

README.md

このファイルには、パッケージの Web ページに表示されるメインコンテンツが含まれています。ファイルの内容は Markdown を使用してマークアップする必要があります。優れた README の書き方については、パッケージページの作成を参照してください。

CHANGELOG.md

このファイルが見つかった場合、パッケージの Web ページに独自のタブが作成されます。開発者は pub.dev から直接変更履歴を読むことができます。ファイルの内容は Markdown を使用してマークアップする必要があります。

pubspec.yaml

このファイルは、パッケージの Web ページの右側にパッケージの詳細情報を表示します。ファイルの内容は YAML の規約に従う必要があります。これらの詳細には、説明、ホームページなどが含まれます。

パッケージは、認定発行者 (推奨) または個々の Google アカウントのいずれかを使用して公開できます。認定発行者を使用する利点は以下のとおりです。

• パッケージの利用者は、発行者のドメインが確認済みであることを認識します。
• pub.dev に個人のメールアドレスが表示されるのを避けることができます。代わりに、pub.dev には発行者のドメインと連絡先アドレスが表示されます。
• pub.dev サイトには、検索ページおよび個々のパッケージページでパッケージ名の横に、認定発行者バッジ が表示されます。

認定発行者を作成するには、次の手順に従ってください。

1. pub.dev にアクセスします。

2. Google アカウントを使用して pub.dev にログインします。

3. 右上隅のユーザーメニューから、**発行者を作成** を選択します。

4. 発行者に関連付けるドメイン名を入力します (例: dart.dev)。

5. **発行者を作成** をクリックします。

6. 確認ダイアログで、**OK** を選択します。

7. 求められた場合は、検証フローを完了します。これにより Google Search Console が開きます。

   • DNS レコードを追加した後、Search Console が変更を反映するまでに数時間かかる場合があります。
   • 検証フローが完了したら、手順 4 に戻ります。

dart pub publish コマンドを使用して、パッケージを初めて公開するか、新しいバージョンに更新します。

公開されるパッケージには、パッケージルートディレクトリ下の**すべてのファイル**が含まれますが、以下の例外があります。

• 隠しファイルまたはディレクトリ。これらはドット (.) で始まる名前を持ちます。
• .pubignore または .gitignore ファイルで無視するようにリストされているファイルおよびディレクトリ

git と dart pub publish で異なる無視ルールを使用するには、.pubignore ファイルを作成して、指定されたディレクトリ内の .gitignore ファイルを上書きします。ディレクトリに .pubignore ファイルと .gitignore ファイルの両方が含まれている場合、dart pub publish はそのディレクトリの .gitignore ファイルを*無視*します。.pubignore ファイルは、.gitignore ファイルと同じ形式に従います。

不要なファイルを公開しないように、以下のプラクティスに従ってください。

• 含めたくないファイルはすべて削除するか、.pubignore または .gitignore ファイルに追加してください。
• パッケージをアップロードする際に、dart pub publish --dry-run が公開するファイルとして表示するリストを確認してください。望まないファイルがリストに表示される場合は、アップロードをキャンセルしてください。

dart pub publish の動作をテストするには、ドライランを実行できます。

dart pub publish --dry-run

このコマンドにより、dart pub は次のタスクを実行します。

1. パッケージが pubspec フォーマットとパッケージレイアウト規約に従っていることを検証します。

2. 公開を意図しているすべてのファイルを表示します。

次の例は、transmogrify という名前のパッケージのテスト公開を示しています。

Publishing transmogrify 1.0.0
    .gitignore
    CHANGELOG.md
    README.md
    lib
        transmogrify.dart
        src
            transmogrifier.dart
            transmogrification.dart
    pubspec.yaml
    test
        transmogrify_test.dart

Package has 0 warnings.

準備ができたらパッケージを公開するには、--dry-run 引数を削除してください。

dart pub publish

このコマンドにより、dart pub は次のタスクを実行します。

1. パッケージが pubspec フォーマットとパッケージレイアウト規約に従っていることを検証します。

2. git status がクリーンであることを検証します。git で追跡されているファイルに変更がある場合は警告します。

3. 公開を意図しているすべてのファイルを表示します。

4. pub.dev にパッケージをアップロードします。

パッケージが pub.dev へのアップロードに成功すると、すべての pub ユーザーがそれをダウンロードしたり、プロジェクトで依存したりできるようになります。

たとえば、transmogrify パッケージのバージョン 1.0.0 を公開した場合、別の Dart 開発者はそれを pubspec.yaml に依存関係として追加できます。

dependencies:
  transmogrify: ^1.0.0

pub.dev サイトは、パッケージがサポートするプラットフォームを検出し、それらのプラットフォームをパッケージページに表示します。pub.dev のユーザーは、プラットフォームで検索をフィルタリングできます。

サポートされているプラットフォームの生成リストを変更するには、pubspec.yaml ファイルでサポートされているプラットフォームを指定してください。

パッケージの最初のバージョンを公開したら、GitHub Actions または Google Cloud サービスアカウントを介して自動公開を設定できます。自動公開の詳細については、pub.dev へのパッケージの自動公開を参照してください。

パッケージを開発する際には、プレリリースとして公開することを検討してください。プレリリースは、次のような場合に役立ちます。

• パッケージの次のメジャーバージョンの開発が活発な場合。
• パッケージの次のリリース候補のベータテスターを募集したい場合。
• パッケージが Dart SDK または Flutter SDK の不安定なバージョンに依存している場合。

セマンティックバージョニングで説明されているように、バージョンのプレリリースを作成するには、バージョンにサフィックスを追加します。たとえば、バージョン 2.0.0 のプレリリースを作成するには、バージョン 2.0.0-dev.1 を使用します。後でバージョン 2.0.0 をリリースすると、すべての 2.0.0-XXX プレリリースよりも優先されます。

pub は利用可能な安定版リリースを優先するため、プレリリースパッケージのユーザーは依存関係の制約を変更する必要がある場合があります。たとえば、ユーザーがバージョン 2.1.0 のプレリリースをテストしたい場合、^2.0.0 または ^2.1.0 の代わりに ^2.1.0-dev.1 を指定する必要があります。

プレリリースを pub.dev に公開すると、パッケージページにプレリリースと安定版リリースの両方へのリンクが表示されます。プレリリースは、分析スコアに影響を与えず、検索結果に表示されず、パッケージの README.md やドキュメントに取って代わることもありません。

プレビューは、すべての以下の条件が満たされる場合に役立ちます。

• パッケージの次の安定版が完成している。
• そのパッケージバージョンが、Dart SDK の安定版ではまだリリースされていない API または機能に依存している。
• パッケージが依存する API または機能が API 安定であり、安定 SDK に到達する前に変更されないことを認識している。

例として、`package:args` の新しいバージョン 2.0.0 を考えてみましょう。これは Dart 3.0.0-417.1.beta の機能に依存しています。しかし、Dart SDK 3.0.0 の安定版はまだリリースされていません。pubspec.yaml ファイルは次のようになります。

name: args
version: 2.0.0

environment:
  sdk: '^3.0.0-417.1.beta'

このパッケージを pub.dev に公開すると、プレビューバージョンとしてタグ付けされます。次のスクリーンショットはこの状況を示しています。安定版は 1.6.0、プレビュー版は 2.0.0 としてリストされています。

Dart が 3.0.0 の安定版をリリースすると、pub.dev はパッケージリストを更新して、2.0.0 をパッケージの最新（安定）バージョンとして表示します。

このセクションの冒頭にあるすべての条件が満たされている場合は、dart pub publish からの次の警告を無視してください。

「Dart SDK のプレリリース版の SDK 制約を持つパッケージは、それ自体もプレリリース版として公開する必要があります。このパッケージに Dart バージョン 3.0.0-0 が必要な場合、パッケージをプレリリースとして公開することを検討してください。」

パッケージに認定発行者がある場合、そのパッケージの pub.dev ページには発行者のドメインが表示されます。

発行者なしで公開されたパッケージの場合、pub.dev はプライバシー上の理由から発行者を公開しません。発行者フィールドには「未確認アップローダー」と表示されます。

パッケージの最初のバージョンを公開した人が、そのパッケージの追加バージョンをアップロードできる唯一の権限を持つ最初の人物になります。

他の人がバージョンをアップロードできるように、または禁止するには、次のいずれかの方法を実行します。

• パッケージの管理ページ: https://pub.dev/packages/<package>/admin で、承認されたアップローダーを管理します。
• パッケージを認定発行者に移行します。発行者のすべてのメンバーはアップロードが承認されます。

パッケージを認定発行者に移行するには、パッケージのアップローダーであり、認定発行者 の管理者である必要があります。

パッケージを認定発行者に移行するには

1. パッケージのアップローダーとしてリストされている Google アカウントで pub.dev にログインします。

2. パッケージの詳細ページに移動します (例: https://pub.dev/packages/http)。

3. 管理タブを選択します。

4. 発行者の名前を入力し、**発行者に移行** をクリックします。

公開されたパッケージバージョンが、公開から 7 日以内であれば、新しいパッケージ消費者がそのバージョンを採用するのを防ぐことができます。取り消されたバージョンは、取り消しから 7 日以内であれば再度復元できます。

取り消しは削除ではありません。 取り消されたパッケージバージョンは、pub.dev のパッケージのバージョンリストの**取り消されたバージョン**セクションに表示されます。そのパッケージバージョンの詳細ビューには、取り消し済みバッジが表示されます。

パッケージを取り消す前に、代わりに新しいバージョンを公開することを検討してください。パッケージの取り消しは、パッケージユーザーに悪影響を与える可能性があります。

依存関係の制約がない、または緩い依存関係の制約を持つ新しいバージョンを公開した場合、パッケージバージョンを取り消すことが唯一の解決策となる場合があります。パッケージの新しいバージョンを公開しても、バージョンソルバーが古いバージョンを選択するのを止めることはできません。そのバージョンは pub が選択できる唯一のバージョンである可能性があります。不正確な依存関係の制約を持つパッケージバージョンを取り消すと、ユーザーは他の依存関係をアップグレードするか、依存関係の競合が発生するかのどちらかになります。

ただし、パッケージに軽微なバグが含まれている場合は、バージョンを取り消す必要がない場合があります。バグが修正された新しいバージョンを公開し、CHANGELOG.md に修正されたバグの説明を記載してください。これにより、ユーザーは何が起こったのかを理解しやすくなります。新しいバージョンを公開することは、パッケージユーザーへの影響が少なくなります。

パッケージが後で取り消されたパッケージバージョンに依存している場合、そのバージョンが依存パッケージの pubspec.lock ファイルに含まれている限り、そのバージョンを使用できます。既に取り消されている特定のバージョンに依存するには、依存パッケージで pubspec.yaml ファイルの dependency_overrides セクションにバージョンをピン留めする必要があります。

パッケージが取り消されたパッケージバージョンに依存している場合、利用可能な他のバージョンに応じて、そのバージョンから移行する方法について選択肢があります。

ほとんどの場合、取り消されたバージョンを置き換えるために新しいバージョンが公開されています。この場合、dart pub upgrade <package> を実行します。

新しいバージョンが利用できない場合は、最新の非取り消しバージョンにダウングレードすることを検討してください。これには 2 つの方法があります。

1. pub ツールコマンドを使用する

   1. dart pub downgrade <package> を実行して、pubspec.yaml ファイルの制約に一致する指定されたパッケージの最も低いバージョンを取得します。

   2. dart pub upgrade <package> を実行して、利用可能な最新の互換性があり非取り消しのバージョンを取得します。

2. お好みの IDE で pubspec.lock ファイルを編集する

   1. 取り消されたバージョンを持つパッケージのエントリ全体を削除します。

   2. dart pub get を実行して、利用可能な最新の互換性があり非取り消しのバージョンを取得します。

pubspec.lock ファイルを削除して dart pub get を実行することもできますが、これは推奨されません。他の依存関係のバージョン変更につながる可能性があります。

現在のバージョン制約を満たす代替バージョンが利用できない場合は、pubspec.yaml ファイルのバージョン制約を編集し、dart pub upgrade を実行します。

パッケージバージョンの取り消しまたは復元を行うには、まず、パッケージのアップローダーまたは認定発行者管理者である Google アカウントで pub.dev にサインインします。次に、パッケージの管理タブに移動します。そこで、最近のパッケージバージョンを取り消したり復元したりできます。

パッケージは公開されたままでも、アクティブなメンテナンスを受け取っていないことを開発者に示すことができます。これには、パッケージを**提供停止**としてマークする必要があります。

パッケージを提供停止にすると、パッケージは次のようになります。

• pub.dev で公開されたままになります。
• pub.dev で表示可能なままになります。
• 明確な **提供停止** バッジを表示します。
• pub.dev の検索結果に表示されなくなります。

パッケージを提供停止としてマークするには

1. パッケージのアップローダーまたは認定発行者の権限を持つ Google アカウントで pub.dev にサインインします。

2. パッケージの管理タブに移動します。

3. パッケージを提供停止にするには、**「提供停止」としてマーク** を選択します。

代替パッケージを推奨することもできます。

1. 推奨される代替パッケージの下のフィールドに、別のパッケージの名前を入力します。

2. 「推奨される代替パッケージ」を更新 をクリックします。

気が変わった場合は、いつでも提供停止マークを削除できます。