dart-migration-versioning

Dart 言語バージョンの管理

目次

• 基本ガイドライン
• 設定とオーバーライド
• ワークフロー
• 例
• 破壊的変更リファレンス
• 関連スキル

基本ガイドライン

• 移行やリファクタリングを始める前に、pubspec.yaml で現在の言語バージョン要件を確認します。
• 依存関係や SDK を大幅にアップグレードする前に、破壊的変更のログを確認します。
• 段階的な移行（たとえば、大規模なプロジェクトでサウンドな null safety などの新しい言語機能に移行する場合）では、特定のファイルを古いバージョンに固定するために @dart = <version> を使用します。
• バージョンの決定方法を理解します。パッケージのデフォルトの言語バージョンは、pubspec.yaml の SDK 制約の下限によって厳密に決まります。パッチバージョンで新しい言語機能が導入されることはありません。

設定とオーバーライド

パッケージ全体のバージョン設定

pubspec.yaml の environment.sdk 制約を変更して、パッケージ全体のデフォルト言語バージョンを設定します。

ライブラリごとのバージョン選択

特定のコメント構文を使用して、個々のファイルでパッケージ全体の言語バージョンをオーバーライドします。

• // コメント内に @dart 文字列を記述します（/// や /* は使用しないでください）。
• ファイル内の Dart コードより前にコメントを記述します。
• パッケージの残りの部分をアップグレードする間、レガシーコードとの互換性を維持するためにこの方法を使用します。

ワークフロー

タスクの進行状況：言語バージョンの段階的な移行

破壊的変更を含む新しい Dart メジャー／マイナーバージョンにプロジェクトをアップグレードするときは、このワークフローを使用します。

• 現在の状態を分析する：現在のバージョンで dart analyze を実行し、問題のない基準状態を確認します。
• 制約を確認する：pubspec.yaml を調べ、現在の SDK 制約の下限を特定します。
• 破壊的変更を確認する：対象バージョンについて、破壊的変更リファレンスを確認します。
• SDK 制約を更新する：pubspec.yaml の environment.sdk の下限を対象バージョンに変更します。
• 依存関係を解決する：dart pub get を実行します。
• 破損箇所を特定する：dart analyze を実行します。
• 修正に条件付きロジックを適用する：
  • ファイルが小さい、または簡単にリファクタリングできる場合：新しい言語バージョンに準拠するよう、破壊的変更をすぐに修正します。
  • ファイルが複雑、または大規模なレガシーモジュールの一部である場合：移行を先送りするため、ファイルの先頭に // @dart = <previous_version> を追加します。
• 検証する：dart test と dart analyze を実行します → エラーを確認します → 残りの問題を修正します。

例

パッケージの言語バージョンを設定する

# pubspec.yaml
name: my_package
environment:
  # This sets the default language version to Dart 3.3
  sdk: '>=3.3.0 <4.0.0'

ライブラリごとのオーバーライドを適用する

// @dart = 2.19
// The above comment pins this specific file to Dart 2.19, 
// even if the pubspec.yaml specifies Dart 3.0+.

import 'dart:math';

void legacyFunction() {
  // Legacy code implementation
}

破壊的変更リファレンス

重要な Dart の破壊的変更を展開（バージョン 2.12～3.11）

Dart 3.11.0

• Wasm コンパイル：dart:js_util または package:js をインポートするコードは、コンパイルエラーになります。dart:js_interop に移行してください。
• アナライザー：avoid_null_checks_in_equality_operators、prefer_final_parameters、use_if_null_to_convert_nulls_to_bools の lint ルールは非推奨です。

Dart 3.10.0

• SDK：dart CLI と Dart VM は、個別の実行可能ファイル（dartvm）になりました。IA32 プラットフォームのサポートは削除されました。
• Wasm コンパイル：dartify は JS の Promise オブジェクトを JSValue ではなく Dart の Future オブジェクトに変換します。

Dart 3.7.0

• 言語：_ という名前のローカル変数とパラメーターは非バインディングとなり、アクセスできません。
• ライブラリ：レガシー Web ライブラリ（dart:html、dart:js など）は正式に非推奨になりました。package:web と dart:js_interop に移行してください。

Dart 3.5.0

• ランタイム：Dart VM はサウンドでない null safety をサポートしなくなりました。--no-sound-null-safety CLI オプションは削除されました。

### Dart 3.0.0（重大な破壊的変更） - **言語**：Null safety が厳密に適用されます。switch ケースはパターンとして解釈されるようになりました。 - **ミックスイン**：Dart 3.0 以降のライブラリにあるクラス宣言は、デフォルトではミックスインとして使用できなくなりました。 - **コア**：`Iterable`、`ListMixin`、`SetMixin`、`MapMixin` はミックスインクラスになりました。

Dart 2.12.0

• 言語：健全な Null safety がデフォルトで有効になりました。

関連スキル

• dart-web-development
• dart-static-analysis