From 155b44ddb959924b4ec5810c9acde158a4e74d5a Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 23 Jan 2024 22:41:26 -0800 Subject: [PATCH 1/4] Add "Additional resources" section to readme --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index ffc1634..9f34b30 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,7 @@ This action comments on the pull request with a report on the resulting change i - [Example usage](#example-usage) - [Scheduled workflow](#scheduled-workflow) - [Workflow triggered by `pull_request` event](#workflow-triggered-by-pull_request-event) +- [Additional resources](#additional-resources) @@ -152,3 +153,9 @@ jobs: with: sketches-reports-source: ${{ env.SKETCHES_REPORTS_PATH }} ``` + +## Additional resources + +- [Introductory article about **arduino/report-size-deltas**](https://blog.arduino.cc/2021/04/09/test-your-arduino-projects-with-github-actions/) +- [**GitHub Actions** documentation](https://docs.github.com/actions/learn-github-actions/understanding-github-actions) +- [Discuss or request assistance on **Arduino Forum**](https://forum.arduino.cc/) From 677622cf7cbea1413a52abb08eb6a38bd7e4314e Mon Sep 17 00:00:00 2001 From: per1234 Date: Tue, 23 Jan 2024 23:23:49 -0800 Subject: [PATCH 2/4] Use latest versions of action dependencies in example workflows Some GitHub Actions workflows are provided in the readme to demonstrate the use of the action. These workflows have dependencies on the "actions/upload-artifact" and "actions/download-artifact" actions. Previously, these dependencies were pinned to their 3.x major version series. A 4.x major version series of the actions was recently started. It is best practices to use the latest version of actions, so the documentation should demonstrate that. A significant breaking change was introduced in the 4.0.0 release of "actions/upload-artifact": uploading multiple times to the same artifact is no longer allowed. Previously the "Workflow triggered by `pull_request` event" example workflow used a single artifact for the sketches report file produced by the matrix job for each of the boards the sketches were compiled for. It was necessary to adjust the configuration of the workflow to use a separate workflow for each of the sketches report files in order to accommodate the bump fo the "actions/upload-artifact" action dependency. --- README.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 9f34b30..f6a87a6 100644 --- a/README.md +++ b/README.md @@ -98,7 +98,7 @@ jobs: - uses: arduino/compile-sketches@v1 with: enable-deltas-report: true - - uses: actions/upload-artifact@v3 + - uses: actions/upload-artifact@v4 with: name: sketches-reports path: sketches-reports @@ -111,29 +111,30 @@ on: [push, pull_request] env: # It's convenient to set variables for values used multiple times in the workflow SKETCHES_REPORTS_PATH: sketches-reports - SKETCHES_REPORTS_ARTIFACT_NAME: sketches-reports jobs: compile: runs-on: ubuntu-latest strategy: matrix: - fqbn: - - "arduino:avr:uno" - - "arduino:samd:mkrzero" + board: + - fqbn: arduino:avr:uno + artifact-name-suffix: arduino-avr-uno + - fqbn: arduino:samd:mkrzero + artifact-name-suffix: arduino-samd-mkrzero steps: - uses: actions/checkout@v4 - uses: arduino/compile-sketches@v1 with: - fqbn: ${{ matrix.fqbn }} + fqbn: ${{ matrix.board.fqbn }} enable-deltas-report: true sketches-report-path: ${{ env.SKETCHES_REPORTS_PATH }} # This step is needed to pass the size data to the report job - name: Upload sketches report to workflow artifact - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: - name: ${{ env.SKETCHES_REPORTS_ARTIFACT_NAME }} + name: sketches-reports-${{ matrix.board.artifact-name-suffix }} path: ${{ env.SKETCHES_REPORTS_PATH }} # When using a matrix to compile for multiple boards, it's necessary to use a separate job for the deltas report @@ -143,10 +144,9 @@ jobs: runs-on: ubuntu-latest steps: # This step is needed to get the size data produced by the compile jobs - - name: Download sketches reports artifact - uses: actions/download-artifact@v3 + - name: Download sketches reports artifacts + uses: actions/download-artifact@v4 with: - name: ${{ env.SKETCHES_REPORTS_ARTIFACT_NAME }} path: ${{ env.SKETCHES_REPORTS_PATH }} - uses: arduino/report-size-deltas@v1 From 90ad27dbdfed5833b487c61190a4799bc25a5823 Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 24 Jan 2024 08:11:59 -0800 Subject: [PATCH 3/4] Add demonstration workflows for multi-board coverage The readme contains a set of workflows demonstrating the use of the action in the use case where the report workflow is triggered by a `schedule` event. These workflows demonstrate the most simple use case, where sketches are only being compiled for a single board. Although this provides a good introduction into using the action, the action user will often want the system to provide coverage for multiple boards. The configuration of the workflows become significantly more complex, especially now that it is necessary to upload each sketches report to a separate artifact. It will be beneficial to also demonstrate that advanced usage. The demonstration consists of a significant amount of content so putting it in the readme would harm the readability and approachability of that document. For this reason, it is published in a separate document which is linked to from the readme. This "FAQ" document will serve as a container for the addition of more supplemental documentation in the future. --- README.md | 7 +++ docs/FAQ.md | 141 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 148 insertions(+) create mode 100644 docs/FAQ.md diff --git a/README.md b/README.md index f6a87a6..7c35576 100644 --- a/README.md +++ b/README.md @@ -104,6 +104,12 @@ jobs: path: sketches-reports ``` +--- + +**ⓘ** A more advanced example is available in [the **FAQ**](docs/FAQ.md#size-deltas-report-workflow-triggered-by-schedule-event). + +--- + ### Workflow triggered by `pull_request` event ```yaml @@ -157,5 +163,6 @@ jobs: ## Additional resources - [Introductory article about **arduino/report-size-deltas**](https://blog.arduino.cc/2021/04/09/test-your-arduino-projects-with-github-actions/) +- [Frequently asked questions about **arduino/report-size-deltas**](docs/FAQ.md#frequently-asked-questions) - [**GitHub Actions** documentation](https://docs.github.com/actions/learn-github-actions/understanding-github-actions) - [Discuss or request assistance on **Arduino Forum**](https://forum.arduino.cc/) diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 0000000..87f35df --- /dev/null +++ b/docs/FAQ.md @@ -0,0 +1,141 @@ +# Frequently Asked Questions + +## How can I work with sketches reports for multiple boards? + +It is common for Arduino projects to target multiple boards. In this case, the sketch compilation job in the workflow should be configured to compile for each of the target boards in order to provide comprehensive coverage. + +This can be accomplished in an easily maintainable and efficient manner by using a [matrix](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix) to generate a parallel workflow job for each board. + +Each sketch compilation job will generate a [sketches report file](https://github.com/arduino/compile-sketches#sketches-report-path) containing the data the **arduino/report-size-deltas** action will use to produce the size deltas report comment. The sketches report file is passed from the sketch compilation job to the job containing the **arduino/report-size-deltas** step via a [workflow artifact](https://docs.github.com/actions/using-workflows/storing-workflow-data-as-artifacts). + +### Size deltas report workflow triggered by `schedule` event + +#### Sketch compilation workflow + +```yaml +on: + - push + - pull_request + +jobs: + compile: + runs-on: ubuntu-latest + + env: + # It's convenient to set variables for values used multiple times in the workflow. + SKETCHES_REPORTS_PATH: sketches-reports + + strategy: + matrix: + board: + # Each element in the sequence produces a matrix job: + - fqbn: arduino:avr:uno + # This suffix will be used to define a unique name for the sketches report artifact. + artifact-name-suffix: arduino-avr-uno + - fqbn: arduino:samd:mkrzero + artifact-name-suffix: arduino-samd-mkrzero + + steps: + - uses: actions/checkout@v4 + + - uses: arduino/compile-sketches@v1 + with: + enable-deltas-report: true + fqbn: ${{ matrix.board.fqbn }} + sketches-report-path: ${{ env.SKETCHES_REPORTS_PATH }} + + - uses: actions/upload-artifact@v4 + with: + # A fixed prefix on the artifact name allows the arduino/report-size-deltas action to identify the sketches + # report artifacts. + name: sketches-report-${{ matrix.board.artifact-name-suffix }} + path: ${{ env.SKETCHES_REPORTS_PATH }} +``` + +#### Size deltas report workflow + +```yaml +on: + schedule: + - cron: "*/5 * * * *" + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - uses: arduino/report-size-deltas@v1 + with: + # This regular expression matches names of sketches report artifacts produced by sketch compilation workflow. + sketches-reports-source: ^sketches-report-.+ +``` + +#### Overview of sketches report data flow + +```mermaid +%%{ + init: { + 'flowchart': { + 'curve': 'basis' + }, + 'theme': 'base', + 'themeVariables': { + 'clusterBkg': '#ffffff', + 'edgeLabelBackground': '#ffffff', + 'lineColor': '#000000', + 'primaryBorderColor': '#000000', + 'primaryColor': '#f0f0f0', + 'primaryTextColor': '#000000' + } + } +}%% + +flowchart TB + subgraph main[" "] + direction TB + + subgraph compileWorkflow["Sketch compilation workflow run"] + direction TB + + unoJob["arduino:avr:uno
job"] + mkrzeroJob["arduino:samd:mkrzero
job"] + + unoCompile["arduino/compile-sketches
action"] + mkrzeroCompile["arduino/compile-sketches
action"] + + unoReportFile["arduino-avr-uno.json"] + mkrzeroReportFile["arduino-samd-mkrzero.json"] + + unoUpload["actions/upload-artifact
action"] + mkrzeroUpload["actions/upload-artifact
action"] + + unoArtifact["sketches-reports-arduino-avr-uno
artifact"] + mkrzeroArtifact["sketches-reports-arduino-samd-mkrzero
artifact"] + end + + subgraph reportWorkflow["Size deltas report workflow run"] + direction TB + + reportAction["arduino/report-size-deltas
action"] + end + + subgraph pr["Pull request"] + direction TB + + comment["Size deltas report
comment"] + end + + unoJob --> unoCompile + mkrzeroJob --> mkrzeroCompile + unoCompile --> unoReportFile + mkrzeroCompile --> mkrzeroReportFile + unoReportFile --> unoUpload + mkrzeroReportFile --> mkrzeroUpload + unoUpload --> unoArtifact + mkrzeroUpload --> mkrzeroArtifact + + unoArtifact --> reportAction + mkrzeroArtifact --> reportAction + reportAction --> comment + end +``` From 30ab6a1c629b01ff0a36bd259314d389f7074102 Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 24 Jan 2024 08:29:56 -0800 Subject: [PATCH 4/4] Add simple demonstration workflow for `pull_request`-triggered workflow A demonstration workflow is provided in the readme to show how to use the action in the use case where the report workflow is triggered by `pull_request` event. Previously, this workflow demonstrated the more advanced configuration that is required in order to compile for multiple boards. Although this demonstration will be useful to the action users, it might be overwhelming as an introduction to the action usage. A demonstration that only compiles for a single board can be far more simple. Even if the user requires coverage of multiple boards in their application, this will give them a basic understanding of the action usage. The advanced demonstration workflow is hereby moved to the FAQ document, replaced in the readme by a simple demonstration workflow. A link from the readme to the advanced usage demonstration is provided. --- README.md | 41 +++++++----------------------------- docs/FAQ.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 67 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 7c35576..fd63225 100644 --- a/README.md +++ b/README.md @@ -114,51 +114,24 @@ jobs: ```yaml on: [push, pull_request] -env: - # It's convenient to set variables for values used multiple times in the workflow - SKETCHES_REPORTS_PATH: sketches-reports jobs: compile: runs-on: ubuntu-latest - strategy: - matrix: - board: - - fqbn: arduino:avr:uno - artifact-name-suffix: arduino-avr-uno - - fqbn: arduino:samd:mkrzero - artifact-name-suffix: arduino-samd-mkrzero steps: - uses: actions/checkout@v4 - - uses: arduino/compile-sketches@v1 with: - fqbn: ${{ matrix.board.fqbn }} enable-deltas-report: true - sketches-report-path: ${{ env.SKETCHES_REPORTS_PATH }} + - uses: arduino/report-size-deltas@v1 + # Only run the action when the workflow is triggered by a pull request. + if: github.event_name == 'pull_request' +``` - # This step is needed to pass the size data to the report job - - name: Upload sketches report to workflow artifact - uses: actions/upload-artifact@v4 - with: - name: sketches-reports-${{ matrix.board.artifact-name-suffix }} - path: ${{ env.SKETCHES_REPORTS_PATH }} +--- - # When using a matrix to compile for multiple boards, it's necessary to use a separate job for the deltas report - report: - needs: compile # Wait for the compile job to finish to get the data for the report - if: github.event_name == 'pull_request' # Only run the job when the workflow is triggered by a pull request - runs-on: ubuntu-latest - steps: - # This step is needed to get the size data produced by the compile jobs - - name: Download sketches reports artifacts - uses: actions/download-artifact@v4 - with: - path: ${{ env.SKETCHES_REPORTS_PATH }} +**ⓘ** A more advanced example is available in [the **FAQ**](docs/FAQ.md#workflow-triggered-by-pull_request-event). - - uses: arduino/report-size-deltas@v1 - with: - sketches-reports-source: ${{ env.SKETCHES_REPORTS_PATH }} -``` +--- ## Additional resources diff --git a/docs/FAQ.md b/docs/FAQ.md index 87f35df..7417131 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -139,3 +139,63 @@ flowchart TB reportAction --> comment end ``` + +### Workflow triggered by `pull_request` event + +```yaml +on: + - push + - pull_request + +env: + # It's convenient to set variables for values used multiple times in the workflow. + SKETCHES_REPORTS_PATH: sketches-reports + +jobs: + compile: + runs-on: ubuntu-latest + + strategy: + matrix: + board: + # Each element in the sequence produces a matrix job: + - fqbn: arduino:avr:uno + # This suffix will be used to define a unique name for the sketches report artifact. + artifact-name-suffix: arduino-avr-uno + - fqbn: arduino:samd:mkrzero + artifact-name-suffix: arduino-samd-mkrzero + + steps: + - uses: actions/checkout@v4 + + - uses: arduino/compile-sketches@v1 + with: + fqbn: ${{ matrix.board.fqbn }} + enable-deltas-report: true + sketches-report-path: ${{ env.SKETCHES_REPORTS_PATH }} + + # This step is needed to pass the size data to the report job. + - name: Upload sketches report to workflow artifact + uses: actions/upload-artifact@v4 + with: + name: sketches-reports-${{ matrix.board.artifact-name-suffix }} + path: ${{ env.SKETCHES_REPORTS_PATH }} + + # When using a matrix to compile for multiple boards, it's necessary to use a separate job for the deltas report + report: + needs: compile # Wait for the compile job to finish to get the data for the report + if: github.event_name == 'pull_request' # Only run the job when the workflow is triggered by a pull request + runs-on: ubuntu-latest + + steps: + # This step is needed to get the size data produced by the compile jobs + - name: Download sketches reports artifacts + uses: actions/download-artifact@v4 + with: + # All workflow artifacts will be downloaded to this location. + path: ${{ env.SKETCHES_REPORTS_PATH }} + + - uses: arduino/report-size-deltas@v1 + with: + sketches-reports-source: ${{ env.SKETCHES_REPORTS_PATH }} +```