Update gem version to latest

.github/workflows/docker_push.yml

@@ -0,0 +1,24 @@
+# via https://docs.github.com/en/free-pro-team@latest/actions/guides/publishing-docker-images
+# and https://docs.github.com/en/free-pro-team@latest/actions/reference/events-that-trigger-workflows#example-using-multiple-events-with-activity-types-or-configuration
+name: Publish Docker image
+on:
+  push:
+    branches:
+      - latest
+  release:
+    types: [published]
+jobs:
+  push_to_registry:
+    name: Push Docker image to GitHub Packages
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v2
+      - name: Push to GitHub Packages
+        uses: docker/build-push-action@v1
+        with:
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+          registry: docker.pkg.github.com # will need to become ghcr.io eventually
+          repository: arduino-ci/action/ubuntu  # has to match organization and repo name, also has to be lowercase
+          tag_with_ref: true

CHANGELOG.md

@@ -0,0 +1,44 @@
+# Change Log
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+
+## [Unreleased]
+### Added
+- Publish docker image to GitHub packages on `latest` branch and after tagging
+- Instructions for testing locally with Docker
+- Adopt new `arduino_ci` version that enables `CUSTOM_INIT_SCRIPT` and `USE_SUBDIR` environment variables
+- Python dependencies for espXX board compilation (unfortunately assumed to be present in image, not installed by board manager)
+- Instructions for new environment variable `SKIP_LIBRARY_PROPERTIES`
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+
+## [0.1.1] - 2020-12-02
+### Added
+* Instructions for the new environment variables `EXPECT_EXAMPLES` and `EXPECT_UNITTESTS`
+* Documentation now links to unit testing information and `.arduino-ci.yaml`
+
+### Changed
+* Use non-interactive frontend for `apt-get install`
+* Arduino libraries directory is now pre-existing in the image
+* Clarified instructions about badges
+
+
+## [0.1.0] - 2020-11-29
+### Added
+- Initial implementation of action
+
+
+[Unreleased]: https://github.com/Arduino-CI/action/compare/v1.1.0...HEAD
+[0.1.0]: https://github.com/Arduino-CI/arduino_ci/compare/v0.0.0...v0.1.0

Dockerfile

@@ -6,10 +6,12 @@ ARG BUILD_REVISION
 ARG BUILD_VERSION
 
 # Values we set in more than one place in this file
-ARG ARDUINO_CI_REPO="https://github.com/ArduinoCI/action"
-ARG ARDUINO_CI_MAINTAINER="Ian <[email protected]>"
-ARG ARDUINO_CLI_GITREF="tag: 'v1.1.0'"
-#ARG ARDUINO_CLI_GITREF="branch: '2020-12-01_fixes'"
+ARG ARDUINO_CI_ACTION_REPO="https://github.com/ArduinoCI/action"
+ARG ARDUINO_CI_MAINTAINER="Arduino Continuous Integration <[email protected]>"
+ARG ARDUINO_CI_GITREPO="https://github.com/ArduinoCI/arduino_ci.git"
+ARG ARDUINO_CI_GITREF="tag: 'v1.2.0'"
+#ARG ARDUINO_CI_GITREPO="https://github.com/ianfixes/arduino_ci.git"
+#ARG ARDUINO_CI_GITREF="branch: '2020-12-28_wrapup'"
 
 LABEL com.github.actions.name="Arduino CI" \
       com.github.actions.description="Unit testing and example compilation for Arduino libraries" \
@@ -20,13 +22,13 @@ LABEL com.github.actions.name="Arduino CI" \
       org.opencontainers.image.revision=$BUILD_REVISION \
       org.opencontainers.image.version=$BUILD_VERSION \
       org.opencontainers.image.authors=$ARDUINO_CI_MAINTAINER \
-      org.opencontainers.image.url=$ARDUINO_CI_REPO \
+      org.opencontainers.image.url=$ARDUINO_CI_ACTION_REPO \
       org.opencontainers.image.source=$ARDUINO_CI_REPO \
-      org.opencontainers.image.documentation=$ARDUINO_CI_REPO \
+      org.opencontainers.image.documentation=$ARDUINO_CI_ACTION_REPO \
       org.opencontainers.image.vendor="Arduino CI" \
       org.opencontainers.image.description="Unit testing and example compilation for Arduino libraries" \
-      repository=$$ARDUINO_CI_REPO \
-      homepage=$ARDUINO_CI_REPO
+      repository=$$ARDUINO_CI_ACTION_REPO \
+      homepage=$ARDUINO_CI_ACTION_REPO
 
 # Values for debugging
 ENV BUILD_DATE=$BUILD_DATE \
@@ -43,14 +45,21 @@ RUN true \
       curl \
       g++ \
       time \
+      python \
+      python-pip \
+      python3 \
+      python3-pip \
   && apt-get clean \
-  && rm -rf /var/lib/apt/lists/*
+  && rm -rf /var/lib/apt/lists/* \
+  && pip install pyserial \
+  && pip3 install pyserial
 
 # install arduino_ci
 RUN true \
   && mkdir -p /action/bundle \
   && echo "source 'https://rubygems.org'" > $BUNDLE_GEMFILE \
-  && echo "gem 'arduino_ci', git: 'https://github.com/Arduino-CI/arduino_ci.git', $ARDUINO_CLI_GITREF" >> $BUNDLE_GEMFILE \
+#  && echo "gem 'arduino_ci', git: '$ARDUINO_CI_GITREPO', $ARDUINO_CI_GITREF" >> $BUNDLE_GEMFILE \
+  && echo "gem 'arduino_ci', '=1.2.0'" >> $BUNDLE_GEMFILE \
   && cat $BUNDLE_GEMFILE \
   && bundle install --gemfile /action/Gemfile --path /action/bundle \
   && find /action |grep arduino_ci.rb

README.md

@@ -1,14 +1,15 @@
 # Arduino-CI GitHub Action
 
-This repository is for the **GitHub Action** to run [`arduino_ci`](https://github.com/Arduino-CI/arduino_ci) on a repository containing an Arduino library.
+This repository is for the **GitHub Action** to run [`arduino_ci`](https://github.com/Arduino-CI/arduino_ci) on a repository containing an Arduino library.  You can also run it locally with Docker, _right now_, if that's easier -- see below.
+
 
 ## Why You Should Use This Action
 
 - Contributions to your Arduino library are tested automatically, _without_ the need for hardware present
 - Example sketches in your `examples/` directory are compiled automatically, to detect broken code in the default branch
+- `library.properties` is scanned for correctness
 
-
-## Adding Arduino CI To Your Project
+## Adding Arduino CI Pull Request Tests To Your Project
 
 1. Create a new YAML file in your repository's `.github/workflows` directory, e.g. `.github/workflows/arduino_test_runner.yml`
 2. Copy an example workflow from below into that new file, no extra configuration required
@@ -23,7 +24,7 @@ These contents for `.github/workflows/arduino_test_runner.yml` should work for m
 
 ```yml
 ---
-name: Arduino CI
+name: Arduino_CI
 
 on: [pull_request]
 
@@ -33,7 +34,7 @@ jobs:
 
     steps:
       - uses: actions/checkout@v2
-      - uses: Arduino-CI/[email protected].0
+      - uses: Arduino-CI/[email protected].2   # v0.1.2 or the latest version
         env:
           # Not all libraries include examples or unit tests.  The default
           #  behavior of arduino_ci is to assume that "if the files don't
@@ -45,28 +46,58 @@ jobs:
           # If you'd rather have the test runner fail the test in the
           #  absence of either tests or examples, uncommenting either of
           #  the following lines (as appropriate) will enforce that.
+          #
+          # EXPECT_EXAMPLES: false
+          # EXPECT_UNITTESTS: false
+
+          # Scanning library.properties for issues is a relatively new
+          #  feature, and we may not have implemented it perfectly just
+          #  yet.
+          #
+          # If you find that it incorrectly fails your library, you can
+          #  skip it.  (Please open an issue against arduino_ci as well
+          #  so that it can be fixed.)
+          #
+          # SKIP_LIBRARY_PROPERTIES: false
 
-          # EXPECT_EXAMPLES: true
-          # EXPECT_UNITTESTS: true
+          # Not all libraries are in the root directory of a repository.
+          # Specifying the path of the library here (relative to the root
+          # of the repository) will adjust that.
+          #
+          # The default is the current directory
+          #
+          # USE_SUBDIR: .
+
+          # Although dependencies will be installed automatically via the
+          # library manager, your library under test may require an
+          # unofficial version of a dependency.  In those cases, the custom
+          # libraries must be insalled prior to the test execution; those
+          # installation commands should be placed in a shell script (that
+          # will be executed by /bin/sh) and the shell script in your repo.
+          #
+          # Then, set this variable to the path to that file (relative to
+          # the repository root)
+          #
+          # CUSTOM_INIT_SCRIPT: install_dependencies.sh
 ```
 
 ### Status Badges
 
 You can show Arduino CI status with a badge in your repository `README.md`
 
 ```markdown
-[![Arduino CI](https://github.com/<OWNER>/<REPOSITORY>/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
+[![Arduino CI](https://github.com/<OWNER>/<REPOSITORY>/workflows/Arduino_CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
 ```
 
 > Note that
 > * you must replace `<OWNER>` with your GitHub username
 > * you must replace `<REPOSITORY>` with the name of the GitHub repository
-> * `Arduino%20CI` in the URL must match the `name: Arduino CI` line in the example YAML files above
+> * `Arduino_CI` in the URL must match the `name: Arduino_CI` line in the example YAML files above
 
 
 ## Configuring Behavior of the Arduino CI Test Runner Itself
 
-When configuring the test runner itself, it's more efficient to run `arduino_ci` locally -- it works on the same OSes as the Arduino IDE.  Instructions for setting that up can be found at [the `arduino_ci` project homepage on GitHub](https://github.com/Arduino-CI/arduino_ci).
+When configuring the test runner itself, it's more efficient to run `arduino_ci` locally -- it works on the same OSes as the Arduino IDE.  Instructions for setting that up can be found at [the `arduino_ci` project homepage on GitHub](https://github.com/Arduino-CI/arduino_ci).  If you are using OSX or Linux, you have the additional option of running Arduino CI directly from Docker -- see below.
 
 
 ### Writing Unit Tests
@@ -76,6 +107,93 @@ For information on Arduino unit testing with `arduino_ci`, see the [`REFERENCE.m
 
 ### Testing Different Arduino Platforms
 
-By default, any unit tests and example sketches are tested against a modest set of Arduino platforms.  This configuration can be overridden in several specific ways; for details, see the [`REFERENCE.md` for Arduino CI's section on CI configuration](https://github.com/Arduino-CI/arduino_ci/blob/master/REFERENCE.md#indirectly-overriding-build-behavior-medium-term-use-and-advanced-options)
+By default, any unit tests and example sketches are tested against a modest set of Arduino platforms.  If you have architectures defined in `library.properties`, that will further refine the set of what is tested.  You can further override this configuration in several specific ways; for details, see the [`REFERENCE.md` for Arduino CI's section on CI configuration](https://github.com/Arduino-CI/arduino_ci/blob/master/REFERENCE.md#indirectly-overriding-build-behavior-medium-term-use-and-advanced-options)
 
 The default configuration is [available in the `arduino_ci` project](https://github.com/Arduino-CI/arduino_ci/blob/master/misc/default.yml), and shows how the platforms and packages are configured (including 3rd-party board provider information).
+
+
+## Immediate Usage / Development Workflow using Docker
+
+The same Docker image used by the GitHub action is available for local testing, and should function properly on Linux and OSX hosts with [Docker](https://www.docker.com/products/docker-desktop) installed.  Choose the command that best matches the state of your project, and use the `-
+
+
+### Your Arduino Libraries directory has everything set up just right; you just want to get up and running and not worry about dependencies at all
+
+Path                               |Contents
+-----------------------------------|--------
+`/pathTo/Arduino/libraries`        | Arduino's libraries directory
+`/pathTo/Arduino/libraries/mylib`  | Your library under test, called `mylib`
+`/pathTo/Arduino/libraries/custom` | A custom library
+
+In this situation, you've got a mix of libraries installed locally (the one that will be tested amongst any possible dependencies), and they all work as expected (even though you're not quite sure all of them are up to date, nor whether they have local modifications that aren't part of the official library release).  This setup won't work in CI, but by volume-mounting the libraries directory into the container and using your own library as the working directory, you can ensure that arduino_ci is using the _exact_ same set of dependencies.
+
+> This is also the fastest way to test new versions of dependencies.
+
+You would run the following (substituting your own library's name in place of `mylib`):
+
+```bash
+docker run --rm \
+  -v "/pathTo/Arduino/libraries:/root/Arduino/libraries" \
+  --workdir /root/Arduino/libraries/mylib \
+  docker.pkg.github.com/arduino-ci/action/ubuntu
+```
+
+
+### Your Arduino Library uses only "official" library versions as dependencies
+
+ Path                              |Contents
+-----------------------------------|--------
+`/pathTo/Arduino/libraries`        | Arduino's libraries directory
+`/pathTo/Arduino/libraries/mylib`  | Your library under test
+
+In this situation, the only libraries you need for your library to work are those that you've downloaded directly from the library manager and no special modifications need to be made.  We simply volume mount the library under test into the container, set that directory to be the working directory, and let the `arduino_ci` test runner install the dependencies directly.
+
+If your project does not include a `library.properties` that defines your project's name, you should change `library_under_test` to `mylib`.
+
+```bash
+docker run --rm \
+  -v "/pathTo/Arduino/libraries/mylib:/library_under_test" \
+  --workdir /library_under_test \
+  docker.pkg.github.com/arduino-ci/action/ubuntu
+```
+
+
+### Your Arduino Library uses libraries or versions as dependencies that can't be installed by name from the Arduino library manager (but you wrote a script to install them automatically)
+
+ Path                                         |Contents
+----------------------------------------------|--------
+`/pathTo/Arduino/libraries`                   | Arduino's libraries directory
+`/pathTo/Arduino/libraries/mylib`             | Your library under test
+`/pathTo/Arduino/libraries/mylib/install.sh`  | Shell script to install custom library
+`/pathTo/Arduino/libraries/custom`            | A custom library
+
+In this situation, you have a custom library that can't be installed by the library manager.  Fortunately, you've supplied an `install.sh` script that will download and unpack a library to the current working directory (which Arduino CI's test runner will run from inside the container's Arduino libraries directory).  Note the _relative_ path used for `install.sh`.
+
+```bash
+docker run --rm \
+  -v "/pathTo/Arduino/libraries/mylib:/library_under_test" \
+  --workdir /library_under_test \
+  --env CUSTOM_INIT_SCRIPT=install.sh \
+  docker.pkg.github.com/arduino-ci/action/ubuntu
+```
+
+
+### Your Arduino Library is a subdirectory of a monorepo, you need libraries or versions as dependencies that can't be installed by name from the Arduino library manager, you wrote a script to install them automatically
+
+ Path                                         |Contents
+----------------------------------------------|--------
+`/pathTo/Arduino/libraries`                   | Arduino's libraries directory
+`/pathTo/Arduino/libraries/custom`            | A custom library
+`/pathTo/Monorepo/mylib`                      | Your library under test
+`/pathTo/Monorepo/mylib/install.sh`           | Shell script to install custom library
+
+All the bells and whistles.
+
+```bash
+docker run --rm \
+  -v "/pathTo/Monorepo:/library_under_test" \
+  --workdir /library_under_test \
+  --env USE_SUBDIR=mylib \
+  --env CUSTOM_INIT_SCRIPT=install.sh \
+  docker.pkg.github.com/arduino-ci/action/ubuntu
+```