From dbc79b7eca99176555cf9d86fefedc78815e79dd Mon Sep 17 00:00:00 2001 From: per1234 Date: Fri, 11 Sep 2020 06:10:02 -0700 Subject: [PATCH 01/12] Add badges to readme to indicate CI status --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index e0cd634..26083ca 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,10 @@ # arduino/compile-sketches action +[![Tests](https://github.com/arduino/compile-sketches/workflows/Test%20Python%20code/badge.svg)](https://github.com/arduino/compile-sketches/actions?workflow=Test+Python+code) +[![Lint](https://github.com/arduino/compile-sketches/workflows/Lint%20Python%20code/badge.svg)](https://github.com/arduino/compile-sketches/actions?workflow=Lint+Python+code) +[![Spell Check](https://github.com/arduino/compile-sketches/workflows/Spell%20Check/badge.svg)](https://github.com/arduino/compile-sketches/actions?workflow=Spell+Check) +[![codecov](https://codecov.io/gh/arduino/compile-sketches/branch/master/graph/badge.svg)](https://codecov.io/gh/arduino/compile-sketches) + This action checks whether Arduino sketches compile and produces a report of data from the compilations. ## Inputs From bc91ec50166dc77fa46312f15ae5198109ececc1 Mon Sep 17 00:00:00 2001 From: per1234 Date: Fri, 11 Sep 2020 06:11:27 -0700 Subject: [PATCH 02/12] Correct branch name shown in example snippets in readme Unlike the original repository, this repository uses a default branch named `main` instead of `master`. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 26083ca..5324f6c 100644 --- a/README.md +++ b/README.md @@ -133,7 +133,7 @@ Set to `true` to cause the action to record the compiler warning count for each Only compiling examples: ```yaml -- uses: arduino/compile-sketches@master +- uses: arduino/compile-sketches@main with: fqbn: 'arduino:avr:uno' libraries: | @@ -144,7 +144,7 @@ Only compiling examples: Storing the sketches compilation report report as a [workflow artifact](https://help.github.com/en/actions/configuring-and-managing-workflows/persisting-workflow-data-using-artifacts): ```yaml -- uses: arduino/compile-sketches@master +- uses: arduino/compile-sketches@main with: enable-deltas-report: true - if: github.event_name == 'pull_request' From 1e4038e9815c96117ff2a7fd967e5ac3a3080f7e Mon Sep 17 00:00:00 2001 From: per1234 Date: Fri, 11 Sep 2020 08:06:25 -0700 Subject: [PATCH 03/12] Format the documentation to make default input values easy to find Previously, the information on whether an input had a default value -- and if so, what -- was incorporated into the input description. This meant you had to read the entire description to find this information. When using other actions, I have regularly had difficulty determining which inputs are required and default input values. I would like for the users of this action to not have that experience. --- README.md | 95 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 62 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 5324f6c..eeef9c4 100644 --- a/README.md +++ b/README.md @@ -11,11 +11,15 @@ This action checks whether Arduino sketches compile and produces a report of dat ### `cli-version` -The version of [Arduino CLI](https://github.com/arduino/arduino-cli) to use. Default `"latest"`. +The version of [Arduino CLI](https://github.com/arduino/arduino-cli) to use. + +**Default**: `"latest"` ### `fqbn` -The fully qualified board name to use when compiling. Default `"arduino:avr:uno"`. +The fully qualified board name to use when compiling. + +**Default**: `"arduino:avr:uno"` If the board is from one of the platforms provided by Arduino's [default package index](https://downloads.arduino.cc/packages/package_index.json), the board's platform dependency will be automatically detected and the latest version installed. For boards of platforms not in the default package index, previous versions, or other platform sources, the platform dependency must be defined via the [`platforms` input](#platforms). @@ -23,7 +27,7 @@ If the board is from one of the platforms provided by Arduino's [default package YAML-format list of platform dependencies to install. -Default `""`. If no `platforms` input is provided, the board's dependency will be automatically determined from the `fqbn` input and the latest version of that platform will be installed via Boards Manager. +**Default**: The board's dependency will be automatically determined from the `fqbn` input and the latest version of that platform will be installed via Boards Manager. If a platform dependency from a non-Boards Manager source of the same name as another Boards Manager source platform dependency is defined, they will both be installed, with the non-Boards Manager dependency overwriting the Boards Manager platform installation. This permits testing against a non-release version of a platform while using Boards Manager to install the platform's tools dependencies. Example: @@ -41,36 +45,42 @@ platforms: | ##### Boards Manager Keys: -- `name` - platform name in the form of `VENDOR:ARCHITECTURE`. -- `version` - version of the platform to install. Default is the latest version. -- `source-url` - Boards Manager URL of the platform. Default is Arduino's package index, which allows installation of all official platforms. +- `name` - (**required**) platform name in the form of `VENDOR:ARCHITECTURE`. +- `version` - version of the platform to install. + - **Default**: the latest version. +- `source-url` - Boards Manager URL of the platform. + - **Default**: Arduino's package index, which allows installation of all official platforms. ##### Local path Keys: -- `source-path` - path to install as a platform. Relative paths are assumed to be relative to the root of the repository. -- `name` - platform name in the form of `VENDOR:ARCHITECTURE`. +- `source-path` - (**required**) path to install as a platform. Relative paths are assumed to be relative to the root of the repository. +- `name` - (**required**) platform name in the form of `VENDOR:ARCHITECTURE`. ##### Repository Keys: -- `source-url` - URL to clone the repository from. It must start with `git://` or end with `.git`. -- `version` - [Git ref](https://git-scm.com/book/en/v2/Git-Internals-Git-References) of the repository to checkout. The special version name `latest` will cause the latest tag to be used. By default, the repository will be checked out to the tip of the default branch. -- `source-path` - path to install as a platform. Paths are relative to the root of the repository. The default is to install from the root of the repository. -- `name` - platform name in the form of `VENDOR:ARCHITECTURE`. +- `source-url` - (**required**) URL to clone the repository from. It must start with `git://` or end with `.git`. +- `name` - (**required**) platform name in the form of `VENDOR:ARCHITECTURE`. +- `version` - [Git ref](https://git-scm.com/book/en/v2/Git-Internals-Git-References) of the repository to checkout. The special version name `latest` will cause the latest tag to be used. + - **Default**: the repository is checked out to the tip of the default branch. +- `source-path` - path to install as a platform. Paths are relative to the root of the repository. + - **Default**: root of the repository. ##### Archive download Keys: -- `source-url` - download URL for the archive (e.g., `https://github.com/arduino/ArduinoCore-avr/archive/master.zip`). -- `source-path` - path to install as a platform. Paths are relative to the root folder of the archive, or the root of the archive if it has no root folder. The default is to install from the root folder of the archive. -- `name` - platform name in the form of `VENDOR:ARCHITECTURE`. +- `source-url` - (**required**) download URL for the archive (e.g., `https://github.com/arduino/ArduinoCore-avr/archive/master.zip`). +- `name` - (**required**) platform name in the form of `VENDOR:ARCHITECTURE`. +- `source-path` - path to install as a platform. Paths are relative to the root folder of the archive, or the root of the archive if it has no root folder. + - **Default**: root folder of the archive. ### `libraries` YAML-format list of library dependencies to install. -Default `"- source-path: ./"`. This causes the repository to be installed as a library. If there are no library dependencies and you want to override the default, set the `libraries` input to an empty list (`- libraries: '-'`). +**Default**: `"- source-path: ./"` +This causes the repository to be installed as a library. If there are no library dependencies and you want to override the default, set the `libraries` input to an empty list (`- libraries: '-'`). Libraries are installed under the Arduino user folder at `~/Arduino/libraries`. @@ -81,53 +91,72 @@ Note: when the deprecated space-separated list format of this input is used, the ##### Library Manager Keys: -- `name` - name of the library, as defined in the `name` field of its [library.properties](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format) metadata file. The library will be installed to a folder matching the name, but with any spaces replaced by `_`. -- `version` - version of the library to install. Default is the latest version. +- `name` - (**required**) name of the library, as defined in the `name` field of its [library.properties](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format) metadata file. The library will be installed to a folder matching the name, but with any spaces replaced by `_`. +- `version` - version of the library to install. + - **Default**: the latest version. ##### Local path Keys: -- `source-path` - path to install as a library. Relative paths are assumed to be relative to the root of the repository. -- `destination-name` - folder name to install the library to. By default, the folder will be named according to the source repository or subfolder name. +- `source-path` - (**required**) path to install as a library. Relative paths are assumed to be relative to the root of the repository. +- `destination-name` - folder name to install the library to. + - **Default**: the folder will be named according to the source repository or subfolder name. ##### Repository Keys: -- `source-url` - URL to clone the repository from. It must start with `git://` or end with `.git`. -- `version` - [Git ref](https://git-scm.com/book/en/v2/Git-Internals-Git-References) of the repository to checkout. The special version name `latest` will cause the latest tag to be used. By default, the repository will be checked out to the tip of the default branch. -- `source-path` - path to install as a library. Paths are relative to the root of the repository. The default is to install from the root of the repository. -- `destination-name` - folder name to install the library to. By default, the folder will be named according to the source repository or subfolder name. +- `source-url` - (**required**) URL to clone the repository from. It must start with `git://` or end with `.git`. +- `version` - [Git ref](https://git-scm.com/book/en/v2/Git-Internals-Git-References) of the repository to checkout. The special version name `latest` will cause the latest tag to be used. + - **Default**: the tip of the default branch. +- `source-path` - path to install as a library. Paths are relative to the root of the repository. + - **Default**: root of the repository. +- `destination-name` - folder name to install the library to. + - **Default**: named according to the source repository or subfolder name. ##### Archive download Keys: -- `source-url` - download URL for the archive (e.g., `https://github.com/arduino-libraries/Servo/archive/master.zip`). -- `source-path` - path to install as a library. Paths are relative to the root folder of the archive, or the root of the archive if it has no root folder. The default is to install from the root folder of the archive. -- `destination-name` - folder name to install the library to. By default, the folder will be named according to the source archive or subfolder name. +- `source-url` - (**required**) download URL for the archive (e.g., `https://github.com/arduino-libraries/Servo/archive/master.zip`). +- `source-path` - path to install as a library. Paths are relative to the root folder of the archive, or the root of the archive if it has no root folder. + - **Default**: root folder of the archive. +- `destination-name` - folder name to install the library to. + - **Default**: named according to the source archive or subfolder name. ### `sketch-paths` -YAML-format list of paths containing sketches to compile. These paths will be searched recursively. Default `- examples`. +YAML-format list of paths containing sketches to compile. These paths will be searched recursively. + +**Default**: `"- examples"` ### `verbose` -Set to true to show verbose output in the log. Default `false` +Set to true to show verbose output in the log. + +**Default**: `false` ### `sketches-report-path` -Path in which to save a JSON formatted file containing data from the sketch compilations. Should be used only to store reports. Relative paths are relative to [`GITHUB_WORKSPACE`](https://help.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables). The folder will be created if it doesn't already exist. This report is used by the `arduino/report-size-deltas` and `arduino/report-size-trends` actions. Default `"size-deltas-reports"`. +Path in which to save a JSON formatted file containing data from the sketch compilations. Should be used only to store reports. Relative paths are relative to [`GITHUB_WORKSPACE`](https://help.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables). The folder will be created if it doesn't already exist. This report is used by the `arduino/report-size-deltas` and `arduino/report-size-trends` actions. + +**Default**: `"size-deltas-reports"` ### `github-token` -GitHub access token used to get information from the GitHub API. Only needed for private repositories with `enable-deltas-report` set to `true`. It will be convenient to use [`${{ secrets.GITHUB_TOKEN }}`](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token). Default `""`. +GitHub access token used to get information from the GitHub API. Only needed for private repositories with `enable-deltas-report` set to `true`. It will be convenient to use [`${{ secrets.GITHUB_TOKEN }}`](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token). + +**Default**: `""` ### `enable-deltas-report` -Set to `true` to cause the action to determine the change in memory usage and compiler warnings of the compiled sketches. If the workflow is triggered by a `pull_request` event, the comparison is between the pull request branch and the tip of the pull request's base branch. If the workflow is triggered by a `push` event, the comparison is between the pushed commit and its immediate parent. The deltas will be displayed in the GitHub Actions build log. This may be used with the [`arduino/report-size-deltas` action](https://github.com/arduino/report-size-deltas). Default `false`. +Set to `true` to cause the action to determine the change in memory usage and compiler warnings of the compiled sketches. If the workflow is triggered by a `pull_request` event, the comparison is between the pull request branch and the tip of the pull request's base branch. If the workflow is triggered by a `push` event, the comparison is between the pushed commit and its immediate parent. The deltas will be displayed in the GitHub Actions build log. This may be used with the [`arduino/report-size-deltas` action](https://github.com/arduino/report-size-deltas). + +**Default**: `false` ### `enable-warnings-report` -Set to `true` to cause the action to record the compiler warning count for each sketch compilation in the sketches report. Default `false`. +Set to `true` to cause the action to record the compiler warning count for each sketch compilation in the sketches report. + +**Default**: `false` ## Example usage From f60eebf6f299a66b1ab1a96952a6d2be475e548b Mon Sep 17 00:00:00 2001 From: per1234 Date: Fri, 11 Sep 2020 08:27:23 -0700 Subject: [PATCH 04/12] Improve formatting of readme --- README.md | 54 +++++++++++++++++++++++++++--------------------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index eeef9c4..0dc85d3 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# arduino/compile-sketches action +# `arduino/compile-sketches` action [![Tests](https://github.com/arduino/compile-sketches/workflows/Test%20Python%20code/badge.svg)](https://github.com/arduino/compile-sketches/actions?workflow=Test+Python+code) [![Lint](https://github.com/arduino/compile-sketches/workflows/Lint%20Python%20code/badge.svg)](https://github.com/arduino/compile-sketches/actions?workflow=Lint+Python+code) @@ -40,39 +40,39 @@ platforms: | name: "arduino:samd" ``` -#### Sources: +#### Supported platform sources: ##### Boards Manager Keys: -- `name` - (**required**) platform name in the form of `VENDOR:ARCHITECTURE`. -- `version` - version of the platform to install. +- **`name`** - (**required**) platform name in the form of `VENDOR:ARCHITECTURE`. +- **`version`** - version of the platform to install. - **Default**: the latest version. -- `source-url` - Boards Manager URL of the platform. +- **`source-url`** - Boards Manager URL of the platform. - **Default**: Arduino's package index, which allows installation of all official platforms. ##### Local path Keys: -- `source-path` - (**required**) path to install as a platform. Relative paths are assumed to be relative to the root of the repository. -- `name` - (**required**) platform name in the form of `VENDOR:ARCHITECTURE`. +- **`source-path`** - (**required**) path to install as a platform. Relative paths are assumed to be relative to the root of the repository. +- **`name`** - (**required**) platform name in the form of `VENDOR:ARCHITECTURE`. ##### Repository Keys: -- `source-url` - (**required**) URL to clone the repository from. It must start with `git://` or end with `.git`. -- `name` - (**required**) platform name in the form of `VENDOR:ARCHITECTURE`. -- `version` - [Git ref](https://git-scm.com/book/en/v2/Git-Internals-Git-References) of the repository to checkout. The special version name `latest` will cause the latest tag to be used. +- **`source-url`** - (**required**) URL to clone the repository from. It must start with `git://` or end with `.git`. +- **`name`** - (**required**) platform name in the form of `VENDOR:ARCHITECTURE`. +- **`version`** - [Git ref](https://git-scm.com/book/en/v2/Git-Internals-Git-References) of the repository to checkout. The special version name `latest` will cause the latest tag to be used. - **Default**: the repository is checked out to the tip of the default branch. -- `source-path` - path to install as a platform. Paths are relative to the root of the repository. +- **`source-path`** - path to install as a platform. Paths are relative to the root of the repository. - **Default**: root of the repository. ##### Archive download Keys: -- `source-url` - (**required**) download URL for the archive (e.g., `https://github.com/arduino/ArduinoCore-avr/archive/master.zip`). -- `name` - (**required**) platform name in the form of `VENDOR:ARCHITECTURE`. -- `source-path` - path to install as a platform. Paths are relative to the root folder of the archive, or the root of the archive if it has no root folder. +- **`source-url`** - (**required**) download URL for the archive (e.g., `https://github.com/arduino/ArduinoCore-avr/archive/master.zip`). +- **`name`** - (**required**) platform name in the form of `VENDOR:ARCHITECTURE`. +- **`source-path`** - path to install as a platform. Paths are relative to the root folder of the archive, or the root of the archive if it has no root folder. - **Default**: root folder of the archive. ### `libraries` @@ -84,42 +84,42 @@ This causes the repository to be installed as a library. If there are no library Libraries are installed under the Arduino user folder at `~/Arduino/libraries`. -Note: when the deprecated space-separated list format of this input is used, the repository under test will always be installed as a library. +**Note**: when the deprecated space-separated list format of this input is used, the repository under test will always be installed as a library. -#### Sources: +#### Supported library sources: ##### Library Manager Keys: -- `name` - (**required**) name of the library, as defined in the `name` field of its [library.properties](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format) metadata file. The library will be installed to a folder matching the name, but with any spaces replaced by `_`. -- `version` - version of the library to install. +- **`name`** - (**required**) name of the library, as defined in the `name` field of its [library.properties](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format) metadata file. The library will be installed to a folder matching the name, but with any spaces replaced by `_`. +- **`version`** - version of the library to install. - **Default**: the latest version. ##### Local path Keys: -- `source-path` - (**required**) path to install as a library. Relative paths are assumed to be relative to the root of the repository. -- `destination-name` - folder name to install the library to. +- **`source-path`** - (**required**) path to install as a library. Relative paths are assumed to be relative to the root of the repository. +- **`destination-name`** - folder name to install the library to. - **Default**: the folder will be named according to the source repository or subfolder name. ##### Repository Keys: -- `source-url` - (**required**) URL to clone the repository from. It must start with `git://` or end with `.git`. -- `version` - [Git ref](https://git-scm.com/book/en/v2/Git-Internals-Git-References) of the repository to checkout. The special version name `latest` will cause the latest tag to be used. +- **`source-url`** - (**required**) URL to clone the repository from. It must start with `git://` or end with `.git`. +- **`version`** - [Git ref](https://git-scm.com/book/en/v2/Git-Internals-Git-References) of the repository to checkout. The special version name `latest` will cause the latest tag to be used. - **Default**: the tip of the default branch. -- `source-path` - path to install as a library. Paths are relative to the root of the repository. +- **`source-path`** - path to install as a library. Paths are relative to the root of the repository. - **Default**: root of the repository. -- `destination-name` - folder name to install the library to. +- **`destination-name`** - folder name to install the library to. - **Default**: named according to the source repository or subfolder name. ##### Archive download Keys: -- `source-url` - (**required**) download URL for the archive (e.g., `https://github.com/arduino-libraries/Servo/archive/master.zip`). -- `source-path` - path to install as a library. Paths are relative to the root folder of the archive, or the root of the archive if it has no root folder. +- **`source-url`** - (**required**) download URL for the archive (e.g., `https://github.com/arduino-libraries/Servo/archive/master.zip`). +- **`source-path`** - path to install as a library. Paths are relative to the root folder of the archive, or the root of the archive if it has no root folder. - **Default**: root folder of the archive. -- `destination-name` - folder name to install the library to. +- **`destination-name`** - folder name to install the library to. - **Default**: named according to the source archive or subfolder name. ### `sketch-paths` From f9a7a520a9711ae502f2a5faf2b8efcd9aa4a766 Mon Sep 17 00:00:00 2001 From: per1234 Date: Fri, 11 Sep 2020 10:22:34 -0700 Subject: [PATCH 05/12] Linkify readme text where appropriate to provide easy access to supporting information --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 0dc85d3..960f0e4 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ [![Spell Check](https://github.com/arduino/compile-sketches/workflows/Spell%20Check/badge.svg)](https://github.com/arduino/compile-sketches/actions?workflow=Spell+Check) [![codecov](https://codecov.io/gh/arduino/compile-sketches/branch/master/graph/badge.svg)](https://codecov.io/gh/arduino/compile-sketches) -This action checks whether Arduino sketches compile and produces a report of data from the compilations. +This action checks whether [Arduino](https://www.arduino.cc/) sketches compile and produces a report of data from the compilations. ## Inputs @@ -25,7 +25,7 @@ If the board is from one of the platforms provided by Arduino's [default package ### `platforms` -YAML-format list of platform dependencies to install. +[YAML](https://en.wikipedia.org/wiki/YAML)-format list of platform dependencies to install. **Default**: The board's dependency will be automatically determined from the `fqbn` input and the latest version of that platform will be installed via Boards Manager. @@ -77,7 +77,7 @@ Keys: ### `libraries` -YAML-format list of library dependencies to install. +[YAML](https://en.wikipedia.org/wiki/YAML)-format list of library dependencies to install. **Default**: `"- source-path: ./"` This causes the repository to be installed as a library. If there are no library dependencies and you want to override the default, set the `libraries` input to an empty list (`- libraries: '-'`). @@ -124,7 +124,7 @@ Keys: ### `sketch-paths` -YAML-format list of paths containing sketches to compile. These paths will be searched recursively. +[YAML](https://en.wikipedia.org/wiki/YAML)-format list of paths containing sketches to compile. These paths will be searched recursively. **Default**: `"- examples"` @@ -136,19 +136,19 @@ Set to true to show verbose output in the log. ### `sketches-report-path` -Path in which to save a JSON formatted file containing data from the sketch compilations. Should be used only to store reports. Relative paths are relative to [`GITHUB_WORKSPACE`](https://help.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables). The folder will be created if it doesn't already exist. This report is used by the `arduino/report-size-deltas` and `arduino/report-size-trends` actions. +Path in which to save a JSON formatted file containing data from the sketch compilations. Should be used only to store reports. Relative paths are relative to [`GITHUB_WORKSPACE`](https://help.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables). The folder will be created if it doesn't already exist. This report is used by the [`arduino/report-size-deltas`](https://github.com/arduino/report-size-deltas) and [`arduino/report-size-trends`](https://github.com/arduino/report-size-trends) actions. **Default**: `"size-deltas-reports"` ### `github-token` -GitHub access token used to get information from the GitHub API. Only needed for private repositories with `enable-deltas-report` set to `true`. It will be convenient to use [`${{ secrets.GITHUB_TOKEN }}`](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token). +GitHub access token used to get information from the GitHub API. Only needed for private repositories with [`enable-deltas-report`](#enable-deltas-report) set to `true`. It will be convenient to use [`${{ secrets.GITHUB_TOKEN }}`](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token). **Default**: `""` ### `enable-deltas-report` -Set to `true` to cause the action to determine the change in memory usage and compiler warnings of the compiled sketches. If the workflow is triggered by a `pull_request` event, the comparison is between the pull request branch and the tip of the pull request's base branch. If the workflow is triggered by a `push` event, the comparison is between the pushed commit and its immediate parent. The deltas will be displayed in the GitHub Actions build log. This may be used with the [`arduino/report-size-deltas` action](https://github.com/arduino/report-size-deltas). +Set to `true` to cause the action to determine the change in memory usage and compiler warnings of the compiled sketches. If the workflow is triggered by a [`pull_request` event](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#pull_request), the comparison is between the pull request branch and the tip of the pull request's base branch. If the workflow is triggered by a [`push` event](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#push), the comparison is between the pushed commit and its immediate parent. The deltas will be displayed in the GitHub Actions build log. This may be used with the [`arduino/report-size-deltas` action](https://github.com/arduino/report-size-deltas). **Default**: `false` From 6b42c370ff72674d98ef3e1939757ccb38303854 Mon Sep 17 00:00:00 2001 From: per1234 Date: Fri, 11 Sep 2020 11:10:29 -0700 Subject: [PATCH 06/12] Add example of platform name in documentation of inputs Even though the generic form was already provided, people who only use the IDEs will not necessarily be familiar with this notation. --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 960f0e4..522e25e 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ platforms: | ##### Boards Manager Keys: -- **`name`** - (**required**) platform name in the form of `VENDOR:ARCHITECTURE`. +- **`name`** - (**required**) platform name in the form of `VENDOR:ARCHITECTURE` (e.g., `arduino:avr`). - **`version`** - version of the platform to install. - **Default**: the latest version. - **`source-url`** - Boards Manager URL of the platform. @@ -55,13 +55,13 @@ Keys: Keys: - **`source-path`** - (**required**) path to install as a platform. Relative paths are assumed to be relative to the root of the repository. -- **`name`** - (**required**) platform name in the form of `VENDOR:ARCHITECTURE`. +- **`name`** - (**required**) platform name in the form of `VENDOR:ARCHITECTURE` (e.g., `arduino:avr`). ##### Repository Keys: - **`source-url`** - (**required**) URL to clone the repository from. It must start with `git://` or end with `.git`. -- **`name`** - (**required**) platform name in the form of `VENDOR:ARCHITECTURE`. +- **`name`** - (**required**) platform name in the form of `VENDOR:ARCHITECTURE` (e.g., `arduino:avr`). - **`version`** - [Git ref](https://git-scm.com/book/en/v2/Git-Internals-Git-References) of the repository to checkout. The special version name `latest` will cause the latest tag to be used. - **Default**: the repository is checked out to the tip of the default branch. - **`source-path`** - path to install as a platform. Paths are relative to the root of the repository. @@ -71,7 +71,7 @@ Keys: Keys: - **`source-url`** - (**required**) download URL for the archive (e.g., `https://github.com/arduino/ArduinoCore-avr/archive/master.zip`). -- **`name`** - (**required**) platform name in the form of `VENDOR:ARCHITECTURE`. +- **`name`** - (**required**) platform name in the form of `VENDOR:ARCHITECTURE` (e.g., `arduino:avr`). - **`source-path`** - path to install as a platform. Paths are relative to the root folder of the archive, or the root of the archive if it has no root folder. - **Default**: root folder of the archive. From 6cb375acf7d7d1f1f842d88eb0619988f2b99205 Mon Sep 17 00:00:00 2001 From: per1234 Date: Sun, 13 Sep 2020 06:21:51 -0700 Subject: [PATCH 07/12] Remove unnecessary conditional from example workflow snippet Now that arduino/compile-sketches always generates a sketches report, the conditional in the workflow snippet in the readme is unnecessary. Although a user may decide they want to do advanced configuration of their workflow to control when the artifact is generated, there is no requirement that it only be made on pull_request events, so this only adds unnecessary complexity to the example. The example should contain only the minimum necessary to effectively demonstrate the basic use of the action. --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 522e25e..e57160b 100644 --- a/README.md +++ b/README.md @@ -176,8 +176,7 @@ Storing the sketches compilation report report as a [workflow artifact](https:// - uses: arduino/compile-sketches@main with: enable-deltas-report: true -- if: github.event_name == 'pull_request' - uses: actions/upload-artifact@v1 +- uses: actions/upload-artifact@v1 with: name: size-deltas-reports path: size-deltas-reports From 87fad667afaab26b562ed70afbd2c3d0f3c33586 Mon Sep 17 00:00:00 2001 From: per1234 Date: Sun, 13 Sep 2020 12:43:07 -0700 Subject: [PATCH 08/12] Add line breaks to documentation to improve readability Break up some "walls of text". --- README.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e57160b..c9c583d 100644 --- a/README.md +++ b/README.md @@ -136,7 +136,9 @@ Set to true to show verbose output in the log. ### `sketches-report-path` -Path in which to save a JSON formatted file containing data from the sketch compilations. Should be used only to store reports. Relative paths are relative to [`GITHUB_WORKSPACE`](https://help.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables). The folder will be created if it doesn't already exist. This report is used by the [`arduino/report-size-deltas`](https://github.com/arduino/report-size-deltas) and [`arduino/report-size-trends`](https://github.com/arduino/report-size-trends) actions. +Path in which to save a JSON formatted file containing data from the sketch compilations. Should be used only to store reports. Relative paths are relative to [`GITHUB_WORKSPACE`](https://help.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables). The folder will be created if it doesn't already exist. + +This report is used by the [`arduino/report-size-deltas`](https://github.com/arduino/report-size-deltas) and [`arduino/report-size-trends`](https://github.com/arduino/report-size-trends) actions. **Default**: `"size-deltas-reports"` @@ -148,7 +150,15 @@ GitHub access token used to get information from the GitHub API. Only needed for ### `enable-deltas-report` -Set to `true` to cause the action to determine the change in memory usage and compiler warnings of the compiled sketches. If the workflow is triggered by a [`pull_request` event](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#pull_request), the comparison is between the pull request branch and the tip of the pull request's base branch. If the workflow is triggered by a [`push` event](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#push), the comparison is between the pushed commit and its immediate parent. The deltas will be displayed in the GitHub Actions build log. This may be used with the [`arduino/report-size-deltas` action](https://github.com/arduino/report-size-deltas). +Set to `true` to cause the action to determine the change in memory usage and compiler warnings of the compiled sketches. + +If the workflow is triggered by a [`pull_request` event](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#pull_request), the comparison is between the pull request branch and the tip of the pull request's base branch. + +If the workflow is triggered by a [`push` event](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#push), the comparison is between the pushed commit and its immediate parent. + +The deltas will be displayed in the GitHub Actions build log. + +This may be used with the [`arduino/report-size-deltas` action](https://github.com/arduino/report-size-deltas). **Default**: `false` From 040a3f47284e2d43ded627362d0ac2ea70b2ab4c Mon Sep 17 00:00:00 2001 From: per1234 Date: Sun, 13 Sep 2020 13:11:00 -0700 Subject: [PATCH 09/12] Provide a detailed explanation of how the deltas report is produced Although the user should be able to just set the input to `true` and get deltas, it may sometimes be useful to understand exactly how this data is produced in order to fully understand its meaning. --- README.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index c9c583d..46f1807 100644 --- a/README.md +++ b/README.md @@ -158,10 +158,16 @@ If the workflow is triggered by a [`push` event](https://docs.github.com/en/acti The deltas will be displayed in the GitHub Actions build log. -This may be used with the [`arduino/report-size-deltas` action](https://github.com/arduino/report-size-deltas). +This report may be used with the [`arduino/report-size-deltas` action](https://github.com/arduino/report-size-deltas). **Default**: `false` +#### How it works + +The sketch is first compiled with the repository in [`$GITHUB_WORKSPACE`](https://docs.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables#default-environment-variables) at the state it was at before the action's step. Data from the compilation is recorded in the sketches report. Next, a [`git checkout`] to the [Git ref](https://git-scm.com/book/en/v2/Git-Internals-Git-References) used as the base of the comparison is done and the compilation + data recording process repeated. The delta is the change in the data between the two compilations. + +Dependencies defined via the [`libraries`](#libraries) or [`platforms`](#platforms) inputs are installed via [symlinks](https://en.wikipedia.org/wiki/Symbolic_link), meaning dependencies from local paths under `$GITHUB_WORKSPACE` reflect the deltas checkouts even though they are installed outside `$GITHUB_WORKSPACE`. + ### `enable-warnings-report` Set to `true` to cause the action to record the compiler warning count for each sketch compilation in the sketches report. From 061d56d1de2914c5b61231deebefa1d247b1757c Mon Sep 17 00:00:00 2001 From: per1234 Date: Sun, 13 Sep 2020 13:17:46 -0700 Subject: [PATCH 10/12] Document that automated library dependencies are installed Library authors may define dependencies of the library in the `depends` field of its library.properties metadata file. These dependencies are automatically installed for libraries sourced from Library Manager. --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 46f1807..59f8556 100644 --- a/README.md +++ b/README.md @@ -91,10 +91,14 @@ Libraries are installed under the Arduino user folder at `~/Arduino/libraries`. ##### Library Manager Keys: -- **`name`** - (**required**) name of the library, as defined in the `name` field of its [library.properties](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format) metadata file. The library will be installed to a folder matching the name, but with any spaces replaced by `_`. +- **`name`** - (**required**) name of the library, as defined in the `name` field of its [library.properties](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format) metadata file. - **`version`** - version of the library to install. - **Default**: the latest version. +**Notes**: +- The library will be installed to a folder matching its name, but with any spaces replaced by `_`. +- If the library's author defined dependencies, those libraries will be installed automatically. + ##### Local path Keys: From e8780d2867960623333e0cee9e8630856048b934 Mon Sep 17 00:00:00 2001 From: per1234 Date: Mon, 14 Sep 2020 11:34:57 -0700 Subject: [PATCH 11/12] Add table of contents to readme Generated using https://github.com/jonschlinkert/markdown-toc ``` npm install --global markdown-toc markdown-toc --bullets=- --maxdepth=5 -i ./README.md ``` --- README.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/README.md b/README.md index 59f8556..cdbc3b1 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,36 @@ This action checks whether [Arduino](https://www.arduino.cc/) sketches compile and produces a report of data from the compilations. +## Table of contents + + + +- [Inputs](#inputs) + - [`cli-version`](#cli-version) + - [`fqbn`](#fqbn) + - [`platforms`](#platforms) + - [Supported platform sources:](#supported-platform-sources) + - [Boards Manager](#boards-manager) + - [Local path](#local-path) + - [Repository](#repository) + - [Archive download](#archive-download) + - [`libraries`](#libraries) + - [Supported library sources:](#supported-library-sources) + - [Library Manager](#library-manager) + - [Local path](#local-path-1) + - [Repository](#repository-1) + - [Archive download](#archive-download-1) + - [`sketch-paths`](#sketch-paths) + - [`verbose`](#verbose) + - [`sketches-report-path`](#sketches-report-path) + - [`github-token`](#github-token) + - [`enable-deltas-report`](#enable-deltas-report) + - [How it works](#how-it-works) + - [`enable-warnings-report`](#enable-warnings-report) +- [Example usage](#example-usage) + + + ## Inputs ### `cli-version` From 98519b3a5e6d38bc3df2aee7acf564ee83a1df04 Mon Sep 17 00:00:00 2001 From: per1234 Date: Mon, 14 Sep 2020 11:50:28 -0700 Subject: [PATCH 12/12] Remove off-topic example from readme The likely use for a sketches report workflow artifact is for the `arduino/report-size-deltas` action. Especially now that they are hosted in separate repositories, it makes more sense to provide this example in the documentation of that action alongside the `arduino/report-size-deltas` example that inherently depends on it. --- README.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/README.md b/README.md index cdbc3b1..e271bad 100644 --- a/README.md +++ b/README.md @@ -210,7 +210,6 @@ Set to `true` to cause the action to record the compiler warning count for each ## Example usage -Only compiling examples: ```yaml - uses: arduino/compile-sketches@main with: @@ -220,14 +219,3 @@ Only compiling examples: - name: Stepper version: 1.1.3 ``` - -Storing the sketches compilation report report as a [workflow artifact](https://help.github.com/en/actions/configuring-and-managing-workflows/persisting-workflow-data-using-artifacts): -```yaml -- uses: arduino/compile-sketches@main - with: - enable-deltas-report: true -- uses: actions/upload-artifact@v1 - with: - name: size-deltas-reports - path: size-deltas-reports -```