How to contribute¶

First of all, thanks for contributing! This document provides some basic guidelines for contributing to this repository.

There are several ways you can get involved:

Issue Reports¶

Do you need help or have a question about using Arduino CLI? Support requests should be made to Arduino CLI's dedicatedboard in theArduino forum.

High quality bug reports and feature requests are valuable contributions to the Arduino CLI project.

Before reporting an issue¶

• Give thenightly build a test drive to see if your issue was already resolved.
• Searchexisting pull requests and issues to see if it was already reported. If you have additional information to provide about an existing issue, please comment there. You can use theReactions feature if you only want to express support.

Qualities of an excellent report¶

• The issue title should be descriptive. Vague titles make it difficult to understand the purpose of the issue, which might cause your issue to be overlooked.
• Provide a full set of steps necessary to reproduce the issue. Demonstration code or commands should be complete and simplified to the minimum necessary to reproduce the issue.
• Be responsive. We may need you to provide additional information in order to investigate and resolve the issue.
• If you find a solution to your problem, please comment on your issue report with an explanation of how you were able to fix it and close the issue.

Pull Requests¶

To propose improvements or fix a bug, feel free to submit a PR.

Legal requirements¶

Before we can accept your contributions you have to sign theContributor License Agreement

Pull request checklist¶

In order to ease code reviews and have your contributions merged faster, here is a list of items you can check beforesubmitting a PR:

• Create small PRs that are narrowly focused on addressing a single concern.
• PR titles indirectly become part of the CHANGELOG so it's crucial to provide a good record ofwhat change is being made in the title;why it was made will go in the PR description, along with a link to a GitHub issue if it exists.
• If the PR contains a breaking change, please start the commit message and PR title with the string[breaking]. Don't forget to describe in the PR description and in theUPGRADING.md file what changes users might need to make in their workflow or application due to this PR. A breaking change is a change that forces users to change their code, command-line invocations, build scripts or data files when upgrading from an older version of Arduino CLI.
• Write tests for the code you wrote.
• Open your PR against themaster branch.
• Maintainclean commit history and usemeaningful commit messages. PRs with messy commit history are difficult to review and require a lot of work to be merged.
• Your PR must pass all CI tests before we will merge it. If you're seeing an error and don't think it's your fault, it may not be! The reviewer will help you if there are test failures that seem not related to the change you are making.

Prerequisites¶

To build the Arduino CLI from sources you need the following tools to be available in your local environment:

• Go version 1.21 or later
• Taskfile to help you run the most common tasks from the command line

If you want to run integration tests you will also need:

• A serial port with an Arduino board attached

If you're working on the gRPC interface you will also have to:

• download and installbuf our tool to compile and generate proto files

Building the source code¶

From the project folder root, just run:

taskbuild

The project uses Go modules so dependencies will be downloaded automatically. At the end of the build, you should findanarduino-cli executable in the same folder.

Running the tests¶

There are several checks and test suites in place to ensure the code works as expected and is written in a way that'sconsistent across the whole codebase. To avoid pushing changes that will cause the CI system to fail, you can run mostof the tests locally.

To ensure code style is consistent, run:

taskcheck

To run unit tests:

taskgo:test

To run integration tests (these will take some time and require special setup, see following paragraph):

taskgo:integration-test

Running only some tests¶

By default, all tests from all go packages are run. To run only unit tests from one or more specific packages, you canset the TARGETS environment variable, e.g.:

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

Alternatively, to run only some specific test(s), you can specify a regex to match against the test function name:

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

Both can be combined as well, typically to run only a specific test:

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

Integration tests¶

Being a command line interface, Arduino CLI is heavily interactive and it has to stay consistent in accepting the userinput and providing the expected output and proper exit codes. On top of this, many Arduino CLI features involvecommunicating with external devices, most likely through a serial port, so unit tests can only go so far in giving usconfidence that the code is working.

For these reasons, in addition to regular unit tests the project has a suite of integration tests that actually runArduino CLI in a different process and assess the options are correctly understood and the output is what we expect.

Hardware requirements for running the full suite of integration tests:¶

An Arduino board attached to a serial port. The board must:

• Use one of the VID/PID pairs used by Arduino or their partners (as is the case with all modern official Arduino boards except the classic Nano).
• Accept uploads using the FQBN associated with that VID/PID (which will be the case unless you have installed a custom bootloader or removed the bootloader).

Note that running the integration tests will result in a sketch being uploaded to every attached Arduino board meetingthe above requirements.

Software requirements for running integration tests:¶

A working Go environment. Chances are that you already have Go installed in your system, if this is not the case you candownload the official distribution or use the package manager provided by your Operating System.

Running tests¶

After the software requirements have been installed you should be able to run the tests with:

taskgo:integration-test

This will run the integration tests automatically.

To run specific packages you must rungo test.

gotest-vgithub.com/arduino/arduino-cli/internal/integrationtest/lib

To run very specific test functions:

gotest-vgithub.com/arduino/arduino-cli/internal/integrationtest/lib-runTestLibUpgradeCommand

Dependency license metadata¶

Metadata about the license types of all dependencies is cached in the repository. To update this cache, run thefollowing command from the repository root folder:

task general:cache-dep-licenses

The necessaryLicensed tool can be installed by followingthese instructions.

Configuration files formatting¶

To keep the configurations tidy and in order we usePrettier to automatically format all YAML filesin the project. Keeping and enforcing a formatting standard helps everyone make small PRs and avoids the introduction offormatting changes made by unconfigured editors.

There are several ways to run Prettier. If you're using Visual Studio Code you can easily use theprettier-vscodeextension to automatically format as you write.

Otherwise you can use the following tasks. To do so you'll need to installnpm if not already installed. Check theofficial documentation to learn how to installnpm for your platform.

Ensure the formatting is compliant by running the command:

taskgeneral:format-prettier

When opening a new Pull Request, checks are automatically run to verify that configuration files are correctlyformatted. In case of failures we might ask you to update the PR with correct formatting.

Working on docs¶

Documentation is provided to final users in form of static HTML content generated from a tool calledMkDocs andhosted onGitHub Pages.

Local development¶

Most of the documentation consists of static content written over several Markdown files under thedocs folder at theroot of this git repository but some other content is dynamically generated from the CI pipelines - this is the casewith the command line reference and the gRPC interface, for example.

If you want to check out how the documentation would look after some local changes, you might need to reproduce whathappens in the CI, generating the full documentation website from your personal computer. To run the docs toolchainlocally, you need to have a few dependencies and tools installed:

• Go version 1.17 or later
• Taskfile to help you run the most common tasks from the command line
• A workingPython environment, seethis paragraph if you need to setup one

Before running the toolchain, perform the following operations from the root of the git repository (if you have a Pythonvirtual environment, activate it before proceeding):

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

When working on docs, you can launch a command that will take care of generating the docs, build the static website andstart a local server you can later access with a web browser to see a preview of your changes. From the root of the gitrepository run:

taskwebsite:serve

If you don't see any error, hithttp://127.0.0.1:8000 with your browser to navigate the generated docs.

Docs publishing¶

The present git repository has a special branch calledgh-pages that contains the generated HTML code for the docswebsite; every time a change is pushed to this special branch, GitHub automatically triggers a deployment to pull thechange and publish a new version of the website. Do not open Pull Requests to push changes to thegh-pages branch,that will be done exclusively from the CI.

Docs formatting¶

To keep the documentation tidy and in order we usePrettier to automatically format all Markdownfiles in the project. Keeping and enforcing a formatting standard helps everyone make small PRs and avoids theintroduction of formatting changes made by unconfigured editors.

There are several ways to run Prettier. If you're using Visual Studio Code you can easily use theprettier-vscodeextension to automatically format as you write.

Otherwise you can use the following tasks. To do so you'll need to installnpm if not already installed. Check theofficial documentation to learn how to installnpm for your platform.

Ensure the formatting is compliant by running the command:

taskgeneral:format-prettier

When opening a new Pull Request, checks are automatically run to verify that documentation is correctly formatted. Incase of failures we might ask you to update the PR with correct formatting.

Docs automation¶

In order to avoid unwanted changes to the public website hosting the Arduino CLI documentation, only Mike is allowed topush changes to thegh-pages branch, and this only happens from within the CI, in a workflow namedDeployWebsite.

Details on the documentation publishing system are availablehere.

Internationalization (i18n)¶

In order to support i18n in the CLI, any messages that are intended to be translated should be wrapped in a call toi18n.Tr. This call allows us to build a catalog of translatable strings, replacing the reference string at runtimewith the localized value.

Example usage:

packagemainimport("fmt""github.com/arduino/arduino-cli/internal/i18n")funcmain(){fmt.Println(i18n.Tr("Hello World!"))}

Abouteasyjson golang library¶

We use the hi-performanceeasyjson library to parse the large JSON index files for libraries and platforms. To obtainthe best performance we must do some code generation, this is done viatask go:easyjson-generate. If you ever touchsource code using theeasyjson library, make sure to re-run thego:easyjson-generate task to see if there arechanges in the generated code.

Additional settings¶

If you need to push a commit that's only shipping documentation changes or example files, thus a complete no-op for thetest suite, please start the commit message with the string[skip ci] to skip the build and give that slot tosomeone else who does need it.

If your PR doesn't need to be included in the changelog, please start the commit message and PR title with the string[skip changelog]