How does the CI know what board it is compiling against? That is usually selected in the Arduino IDE but the CI doesn't know how to do this unless you provide it some information.

The Adafruit Learning System uses a zero length file to test and see which microcontroller board it should run the tests on. This takes the form .xxxxx.test.only where xxxxx is a code for the board to test against.

The most current list of test boards is found in the arduino_cron.yml file under arduino-platform https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/.github/workflows/arduino_cron.yml

The detailed platform list is in https://github.com/adafruit/ci-arduino/blob/master/all_platforms.py

If a microcontroller is not listed, then you should contact your Adafruit Learning System facilitator for assistance.

If you are an Adafruit team member, you will need to add the new board entry. The repo for the Arduino CI is https://github.com/adafruit/ci-arduino and it describes various processes in the CI pipeline. It is suggested you get assistance from the CI maintainers with such changes (see the repo for current active maintainers).

Example:

If you have an Adafruit Circuit Playground Express, you look in the file and there is a listing for "cpx_ada". Use that one.

Using your editor, make a file (contents irrelevant, zero length or just a space are fine). Name the file .cpx_ada.test.only and include it in the directory with the .ino file for the project.

If you have examples for multiple microcontroller boards, put each example in it's own subdirectory with an appropriate .test.only file.

An extra step for using TinyUSB

If your sketch uses the TinyUSB USB functionality of compatible boards, you need to make one more check. In githubci.yml, some boards exist in two forms - one with the board name and one with _TinyUSB appended, re.

metro_m4 and metro_m4_tinyusb

The second version with _tinyusb will select compiling the Metro M4 with TinyUSB turned on. Only boards in githubci.yml that have the _tinyusb entry also work with compiling with TinyUSB.

Advanced: for a list of TinyUSB compatible boards, you can also look in CI file https://github.com/adafruit/ci-arduino/blob/master/build_platform.py (note this may have changed in 2023).

What if I don't do this?

The CI will look at the files and not know what board to use in the Arduino IDE run and will give errors as it tries everything. Your submission will not pass and your facilitator will ask you to include the correct .test.only file. You may ask the facilitator to do it for you but you know your project, it's expected you do this yourself.

Advanced: Skip the CI

In very rare cases, like when code is only a template and will not compile, the keyword file .none.test.only might be considered. 

Please discuss with the Guide Moderation Coordinator is you have this edge case. Normal code using this will not be accepted.