貢献方法
Author:ArduinoV1.5.1

貢献方法

まず、貢献していただきありがとうございます。このガイドラインでは、リポジトリに対して貢献するための、いくつかの基本的なガイドラインを示します。

参加するにはいくつかの方法があります。

貢献の種類 貢献方法
- サポート
- 質問
- 議論		 Arduino Forumに投稿してください。
- バグ報告
- 機能要求		 問題報告(ガイドラインを読んでください)
試験 nightly buildを試してください。
- バグ修正
- 拡張		 プルリクエスト作成してください(ガイドラインを読んでください)
Arduino CLIの翻訳 transfixを使ってください。
金銭面 - 寄付
- 公式製品を買う

問題報告

Arduino CLIを使うのに、助けが必要だったり質問がありますか? Arduino ForumにあるArduino CLI専用ボードに、サポートリクエストを出してください。

高品質のバグレポートと機能要求はArduino CLIプロジェクトにとって価値のある貢献です。

課題をレポートする前に

  • nightly buildで試し、課題がすでに解決されているか確認してください。
  • 既存のプルリクエストと課題を検索し、その課題が既に報告されているか確認してください。既存の課題に対して追加情報があれば、そこにコメントしてください。支持を表明するだけだけであれば、リアクション機能が使えます。

素晴らしいレポートの品質

  • 課題のタイトルで課題がわかるようにしてください。曖昧なタイトルは、課題の目的が不明確になり、課題が見落とされるかもしれません。
  • 課題を再現するのに必要な完全な手順を提供してください。デモコードやコマンドは、課題を再現するのに必要な、完全で最小限なものにしてください。
  • 反応してください。課題の調査や解決に追加の情報を求める必要があるかもしれません。
  • 自分の課題の解決策を見つけた場合は、自分の課題に対してコメントし、どのようにして課題を解決できたのかを説明し、課題をクローズしてください。

プルリクエスト

改善やバグ修正を提案するには、PR(Pull Request、プルリクエスト)を提出してください。

法的要件

貢献を受け入れる前に、Contributor License Agreementにサインする必要があります。

プルリクエストチェックリスト

コードレビューを容易にし、より早くマージするための、PR提出前のチェックリストです。

  • 一つの課題に焦点を絞ったPRを作成してください。
  • PRのタイトルは、間接的にCHANGELOGの一部になります。このため、どんな変更が行われるかを、適切にタイトルに記録することが重要です。また、変更理由はPRの説明に記述し、GitHubの課題があれば、リンクも含めます。
  • PRに非互換の変更がある場合は、コメントメッセージとPRタイトルを、**[breaking]**で始めてください。PR説明とUPGRADING.mdファイルで、このPRにより、ユーザーのワークフローやアプリケーション内でどのような変更を行う必要があるのか説明してください。非互換の変更は、Arduino CLIの古いバージョンから更新する際に、ユーザーにコードやコマンドライン呼び出し、ビルドスクリプト、データファイルへの変更を強いります。
  • あなたが書いたコードのテストを書いてください。
  • masterブランチに対してPRをオープンしてください。
  • clean commit historyを保守し、意味のあるコミットメッセージを使ってください。雑なコミット履歴のPRは、レビューが難しくマージするのに多大な労力が必要です。
  • マージする前にPRはすべてのCIテストに合格する必要があります。あなたの責任でないと思うエラーを発見しても、そうではないかもしれません。あなたの変更に関連しないと思われるテストに失敗がある場合、レビューアーが手助けします。

前提条件

Arduino CLIをソースコードから構築するには、以下のツールをローカル環境に用意する必要があります。

  • Goバージョン1.2.1以降
  • コマンドラインからほとんどの共通タスクを実行するのを助けるTaskfile

統合テストを実行するには、以下も必要です。

  • Arduinoボードを接続したシリアルポート

gRPCインターフェイスの作業をしているのであれば、以下も必要です。

  • protoファイルをコンパイル・精製するためのツールであるbufをダウンロードしてインストールしてください。

ソースコートのビルド

プロジェクトのルートフォルダで以下を実行します。

1

task build

プロジェクトはGoモジュールを使います。依存関係のあるものは自動的にダウンロードされます。ビルド後、同じフォルダにarduino-cliの実行形式が作成されています。

テストの実行

コードが期待通りに動作し、コードベース全体で一貫した方法で記述しているかを確認するのに、いくつかのチェックやテストスイートがあります。CIシステムが失敗するような変更をプッシュするのを避けるために、ほとんどのテストをローカルで実行できます。

コードスタイルに一貫性があるかを保証するには、以下を実行してください。

1

task check

単体テストを実行するには、

1

task go: test

統合テスト(これらは時間がかかり、特別な設定が必要です。次のパラグラフを参照してください)

1

task go:integration-test

特定のテストだけの実行

デフォルトでは、すべてのgoパッケージのテストが実行されます。いくつかの特定のパッケージの単体テストだけを実行するには、環境変数TARGETSを設定します。例えば、

1

TARGETS=./arduino/cores/packagemanager task go:test

あるいは、特定の試験だけを実行するには、テスト関数名の正規表現を設定することもできます。

1

TEST_REGEX='^TestTryBuild.*' task go:test

双方を組み合わせ、特定のテストだけを実行することもできます。

1

TEST_REGEX='^TestFindBoardWithFQBN$' TARGETS=./arduino/cores/packagemanager task go:test

統合テスト

Arduino CLIは、コマンドラインインターフェイスなので、ユーザーとのやり取りが多く、ユーザーからの入力の受付と期待する出力と終了コードの提供に関して、一貫性が求められます。さらに、多くのArduino CLIの機能は、外部デバイスとの通信(多くの場合はシリアルポートを通じた)を含みます。このため、単体テストではコードが動作するということ以上の確信は得られません。

このため、通常の単体テストに加え、異なるプロセスでArduino CLIを実際に実行し、オプションが正しく解釈され、期待した出力が得られるかを確認する、一連の統合テストスイートがあります。

完全な統合テストスイートを実行するためのハードウェア要件

シリアルポートに接続されたArduinoボード。ボードは、以下を満たす必要があります。

  • Arduinoやパートナーが利用するVID/PIDペアのどれかを使ってください。古いNanoを除くすべての新しい公式Arduinoボードです。
  • そのVID/PIDに関連づけられたFQBMを使いアップロードすることを受け入れてください。これは、カスタムブートローダーをインストールしていたり、ブートローダーを削除していない場合です。

統合テストを実行すると、上述の要件を満たす、すべての接続したArduinoボードにスケッチがアップロードされることに注意してください。

完全な統合テストスイートを実行するためのソフトウェア要件

実行できるGo環境。システムに、すでにGoをインストールしている場合。そうでない場合は、公式ディストリビューションをダウンロードするか、OSにより提供されるパッケージマネージャーを使ってください。

テストの実行

必要なソフトウェアをインストールしたら、テストを実行可能です。

1

task go:integration-test

統合テストが自動的に実行されます。

特定のパッケージを実行するには、go testを実行します。

1

go test -v github.com/arduino/arduino-cli/internal/integrationtest/lib

特定のテスト関数を実行するには、

1

go test -v github.com/arduino/arduino-cli/internal/integrationtest/lib -run TestLibUpgradeCommand

依存関係のライセンスに関するメタデータ

すべての依存関係のライセンス形式に関するメタデータは、リポジトリにキャッシュされます。このキャッシュを更新するには、リポジトリのルートフォルダで以下のコマンドを実行してください。

1

task general:cache-dep-licenses

必要となるライセンス付きツールは、これらの手順に従ってインストールできます。

設定ファイルのフォーマット

設定ファイルを整理した状態に保つために、Prettierを使い、プロジェクトのすべてのYAMLファイルを自動整形しています。整形の標準に従うことで、小さいPRを作ることができ、整形できないエディタによるフォーマット変更の混入を防ぐことができます。

Prettierを実行するには、いくつかの方法があります。Visual Studio Codeを使っている場合は、記述時に自動整形するためのprettier-vscode拡張を簡単に利用できます。

また、以下のタスクを使うこともできます。そのためには、npmをインストールする必要があります(未インストールの場合)。公式ドキュメントを参照し、あなたのプラットフォームにnpmをインストールする方法を学んでください。

以下のコマンドを実行して、整形が規定に従っているか確認してください。

1

task general:format-prettier

新しいプルリクエストを開く場合は、設定ファイルが正しく整形されているか自動的にチェックされます。チェックが失敗した場合は、正しく整形して、PRを更新するよう依頼します。

ドキュメントに対する作業

ドキュメントは、静的なHTMLコンテンツの形式で最終ユーザーに提供されます。HTMLコンテンツは、MkDocsというツールで生成され、GitHubでホストされます。

ローカル開発

多くのドキュメントは、このgitリポジトリのルートにあるdoscフォルダの下にあるいくつかのMarkdownファイルから構成されます。しかし、いくつかの他のコンテンツはCIパイプラインから動的に生成されます。コマンドラインリファレンスとgRPCインターフェイスがその例です。

ローカルの変更後、ドキュメントがどのように見えるかを確認したければ、あなたのPCからウェブサイトのドキュメントを生成し、CIで何が起こるかを再現する必要があるかもしれません。このドキュメントのツールチェーンを、ローカルで実行するには、いくつかの依存関係とツールをインストールする必要があります。

  • Goバージョン1.17以降
  • コマンドラインからほとんどの共通タスクを実行するのを助けるTaskfile
  • 動作するPython環境。設定するには、このパラグラフを参照してください。

ツールチェーンを実行する前に、gitリポジトリのルートで、以下の操作を実行してください。Python仮想環境を使っている場合は、実行前に有効化してください。

  • go get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc
  • poetry install

ドキュメントに対して作業するときは、ドキュメントの生成、静的なウェブサイトの構築、ウェブブラウザで変更を確認するのにアクセスできるローカルサーバの開始を行うコマンドを実行します。gitリポジトリのルートで以下を実行します。

1

task website:serve

エラーがない場合は、ブラウザで、http://127.0.0.1:8000/ にアクセスし、生成したドキュメントを見てください。

ドキュメントの公開

現在のgitリポジトリには、gh-pagesという特別のブランチがあり、ドキュメントWebサイト向けに生成されたHTMLが含まれています。この特別なブランチに変更がプッシュされるたびに、GitHubは、変更をプルし、新しいバージョンのWebサイトを公開するための、操作を自動起動します。gh-pagesブランチを変更するプッシュを行うために、プルリクエストをオープンしないでください。これは、CIから実行されます。

ドキュメントの整形

ドキュメントを整理した状態に保つために、Prettierを使い、プロジェクトのすべてのYAMLファイルを自動整形しています。整形の標準に従うことで、小さいPRを作ることができ、整形できないエディタによるフォーマット変更の混入を防ぐことができます。

Prettierを実行するには、いくつかの方法があります。Visual Studio Codeを使っている場合は、記述時に自動整形するためのprettier-vscode拡張を簡単に利用できます。

また、以下のタスクを使うこともできます。そのためには、npmをインストールする必要があります(未インストールの場合)。公式ドキュメントを参照し、あなたのプラットフォームにnpmをインストールする方法を学んでください。

以下のコマンドを実行して、整形が規定に従っているか確認してください。

1

task general:format-prettier

新しいプルリクエストを開く場合は、ドキュメントが正しく整形されているか自動的にチェックされます。チェックが失敗した場合は、正しく整形して、PRを更新するよう依頼します。

ドキュメントの自動化

不要な変更で、Arduino CLIのドキュメントをホスティングしているWebサイトが公開されることを避けるために、ph-pagesブランチに対する変更をプッシュできるのはMikeだけです。これは、Deploy Websiteと名付けられたワークフローで、CIからだけ発生します。

システムを公開するドキュメントの詳細はこちら。

国際化(i18n)

CLIでi18nをサポートするには、翻訳されるすべてのメッセージはi18n.Tr呼び出しを行う必要があります。この呼び出しで、翻訳文字列のカタログを構築し、参照された文字列を実行時にローカライズされた値に置き換えます。

利用例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

package main

import (
  "fmt"
  "github.com/arduino/arduino-cli/internal/i18n"
)

func main() {
  fmt.Println(i18n.Tr("Hello World!"))
}

easyjsonGo言語ライブラリについて

ライブラリとプラットフォーム向けの大きいJSONインデックスファイルを解析するのに、高性能なeasyjsonライブラリを使います。最高のパフォーマンスを得るために、いくつかのコードを生成する必要があります。これは、task go:easyjson-generateにより行われます。easyjsonライブラリでソースコードに触れた場合は、生成されたコードに変更があるかを確認するために、go:easyjson-generateを再実行するのを忘れないでください。

追加設定

ドキュメントやスケッチ例の変更だけを配布するコミットをプッシュする必要がある場合、すなわち、テストスイートを全く実行しない場合は、コミットメッセージを[skip ci]という文字列で開始してビルドをスキップし、スロットを必要とする人に渡してください。

PRをChangeLogに含める必要がない場合は、コミットメッセージとPRタイトルを[skip changelog]という文字列で始めてください。

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

オリジナルのページ

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

最終更新日

August 16, 2026

inserted by FC2 system