diff --git a/README.md b/README.md index ffc1634..fd63225 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) @@ -97,58 +98,44 @@ 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 ``` +--- + +**ⓘ** 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 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" steps: - uses: actions/checkout@v4 - - uses: arduino/compile-sketches@v1 with: - fqbn: ${{ matrix.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@v3 - with: - name: ${{ env.SKETCHES_REPORTS_ARTIFACT_NAME }} - 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 artifact - uses: actions/download-artifact@v3 - with: - name: ${{ env.SKETCHES_REPORTS_ARTIFACT_NAME }} - 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 + +- [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..7417131 --- /dev/null +++ b/docs/FAQ.md @@ -0,0 +1,201 @@ +# 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 +``` + +### 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 }} +```