arduino-cliの後方互換性ポリシー

arduino-cliプロジェクトは、厳格なセマンティックバージョニングポリシーに従います。Arduino CLI 1.x.xのマイナーリリースでは、互換性を破る変更を行いません。

リリースのルールは以下の通りです。

アルファフェーズ0.0.X: このフェーズでは、APIは高速イテレーションを行います。各リリース(Xが増加します)は、多くの互換性を破る変更を含む可能性があります。
ベータフェーズ0.Y.X: ソフトウェアは利用可能です。しかし、APIはまだ安定しておらず、継続的な試験とレビューが行われています。互換性を破る変更の可能性もありえます。バグ修正と新機能はパッチリリースとして行われます(Xが増加します)。APIの改善による互換性を破る変更は、マイナーリリースとして行われます(Yが増加します)。
プロダクションリリース候補1.0.0-rc.X: このフェーズでは、ソフトウェアはリリース可能と考えられており、最終テストのためにユーザーに配布されます。リリース候補(Xが増加します)はバグ修正だけが可能です。
プロダクションリリース1.Y.X: プロダクションリリースでは、後方互換性は保証されます。すべての互換性を破る変更は、次のメジャーリリース(2.0.0)に持ち越されます。バグ修正はパッチリリースとして行われます(Xが増加します)。新規機能はマイナーリリースとして行われます(Yが増加します)。
次のメジャーリリース開発>= 2.0.0以降: 以下を参照してください。

後方互換性の保証と「互換性を破る変更」の定義

arduino-cliプロジェクトには、3種類のユーザー向けAPIがあります。

スタンドアローンのコマンドラインAPI
gRPC API
Go言語API

これらの種類ごとに後方互換性ルールを見ていきましょう。

コマンドラインAPIの互換性を破る変更

コマンドラインいんらーフェイスの変更が後方互換性を破る場合は、

コマンドや位置引数、フラグが削除・変更された
コマンドや位置引数、フラグの挙動が変更された
オプションの位置引数やフラグが必須となった
位置引数やフラグのフォーマットが変更された

コマンドラインの文法に対する以下の変更は、後方互換性を破らない。

新規コマンドが追加された
新規オプション位置引数が追加された
新規オプションフラグが追加された

人が読む文字出力に対するすべての変更は、後方互換性を破りません。一般に、人が読むテキストは、翻訳や自然言語構文や表現の小さな調整対象となります。

後方互換性を破る変更とは、--jsonフラグを用いたコマンドの機械可読出力だけが対象と考えています。特に、以下の場合、JSONコマンド出力に、後方互換性を破る変更が行われます。

JSONオブジェクトのキーが変更・削除された
JSONオブジェクトや配列の値の意味やフォーマットが変更された

以下の場合は、後方互換性を破りません。

既存のJSONオブジェクトに新規キーが追加された

gRPC APIの互換性を破る変更

gRPCの後方互換性を保証するために、許容されている変更は以下の通り。

新規サービスの追加
サービスに新規メソッドを追加
既存メッセージにフィールドを追加
列挙型に値を追加

一般に、gRPC APIへの追加は許容されています。他の全ての変更は、後方互換性を破ると考えられています。いくつか例を挙げます。

サービス名の変更
メソッド名の変更
メソッドのシグネチャの変更
メッセージ内のフィールド名の変更
メッセージ内のフィールド型の変更
メッセージ内のフィールドの削除
その他

gRPC APIは、cc.arduino.cli.commands.v1というエンドポイントで動作するgRPCサービスとして定義されます。後方互換性を破る変更が起こると、新しいgRPCエンドポイントが、既存のAPIから作られます。最初の互換性を破る変更はcc.arduino.cli.commands.v2という新サービスとして実装されます。

Go言語APIの互換性を破る変更

github.com/arduino/arduino-cliというインポートパスで公開されているGo言語APIは、安定していることが保証されています。APIの互換性を破る変更は、Go言語ガイドラインに従い、/V2という後置詞を追加してインポートパスを変更することで実装されます。

次のメジャーリリースの開発プロセス

2.0.0リリースの開発は、2.x.xという別のgitブランチで行われます。mastergitブランチで継続開発している1.0.0リリースも並行して開発が行われます。

新機能とバグ修正は、masterブランチに対して実施され、完了すると、2.x.xにポートされます(この変更が2.0.0に特有の変更でない場合です。そうでない場合、2.x.xブランチで直接開発します)。

2.x.xの将来のリリースとプレリリースは、以下のバージョニングポリシーに従います。

Beta2.0.0-beta.X.Y: v2 APIの試験とレビューが行われている状態です。バグ修正と新規機能は、Yを増加してリリースされます。互換性を破る変更はまだ可能で、その場合は、Xを増加してリリースされます。
リリース候補2.0.0-rc.X: v2 APIがリリース可能です。リリース候補はユーザ試験のために配布されます。リリース候補(Xが増加します)はバグ修正だけが可能です。
2.0.0以降: 1.0.0と同じルールが適用されます。

2.0.0リリース以降は、masterブランチは、2.x.xに移され、1.0ブランチは、新しい1.x.xとして開発されます。

CLI2.0のコマンドラインインターフェイスは、CLI 1.0と互換性がありません。いくつかのコマンドは互換性がありますが、変更の度合いに依存します。

gRPCデーモンは、v1とv2のサービスを同時に実行するには、十分柔軟です。この能力により、非推奨期間を設けることができ、v1 APIからv2 APIへの緩やかな以降を可能とします。CLI 2.0シリーズでは、v1 APIを非推奨としますが、次のメジャーリリースであるCLI 3.0が出るまでは、サポートを継続します。その時点で、v1 APIのサポートを完全に停止することを決定するかもしれません。しかし、ユーザーからの要求と維持管理のための手間のバランス次第では、サポートを継続するかもしれません。

Go言語APIのインポートパスは、Goモジュールガイドラインに従い/v2後置詞を付加して更新され、github.com/arduino/arduino-cli/v2となります。

gRPCとは異なり、非推奨ポリシーは保証せず、Go言語APIの緩やかな以降期間は保証しません。しかし、ここでも、ユーザーからの要求と維持管理のための手間のバランス次第では、いくつかのAPIが非推奨とするかもしれません。

このページでは、最新版のArduino CLIを確認できます。過去のバージョンはこちらにあります。

オリジナルのページ

https://docs.arduino.cc/arduino-cli/versioning/

最終更新日

August 1, 2026