Skip to content

Commit b4d8c01

Browse files
per1234per1234
authored
Merge pull request #84 from per1234/add-faq
Demonstrate usage in multi-board coverage applications
2 parents fa666e2 + 30ab6a1 commit b4d8c01

File tree

2 files changed

+223
-35
lines changed

2 files changed

+223
-35
lines changed

‎README.md

+22-35
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ This action comments on the pull request with a report on the resulting change i
2929
- [Example usage](#example-usage)
3030
- [Scheduled workflow](#scheduled-workflow)
3131
- [Workflow triggered by `pull_request` event](#workflow-triggered-by-pull_request-event)
32+
- [Additional resources](#additional-resources)
3233

3334
<!-- tocstop -->
3435

@@ -97,58 +98,44 @@ jobs:
9798
- uses: arduino/compile-sketches@v1
9899
with:
99100
enable-deltas-report: true
100-
- uses: actions/upload-artifact@v3
101+
- uses: actions/upload-artifact@v4
101102
with:
102103
name: sketches-reports
103104
path: sketches-reports
104105
```
105106

107+
---
108+
109+
**ⓘ** A more advanced example is available in [the **FAQ**](docs/FAQ.md#size-deltas-report-workflow-triggered-by-schedule-event).
110+
111+
---
112+
106113
### Workflow triggered by `pull_request` event
107114

108115
```yaml
109116
on: [push, pull_request]
110-
env:
111-
# It's convenient to set variables for values used multiple times in the workflow
112-
SKETCHES_REPORTS_PATH: sketches-reports
113-
SKETCHES_REPORTS_ARTIFACT_NAME: sketches-reports
114117
jobs:
115118
compile:
116119
runs-on: ubuntu-latest
117-
strategy:
118-
matrix:
119-
fqbn:
120-
- "arduino:avr:uno"
121-
- "arduino:samd:mkrzero"
122120
steps:
123121
- uses: actions/checkout@v4
124-
125122
- uses: arduino/compile-sketches@v1
126123
with:
127-
fqbn: ${{ matrix.fqbn }}
128124
enable-deltas-report: true
129-
sketches-report-path: ${{ env.SKETCHES_REPORTS_PATH }}
125+
- uses: arduino/report-size-deltas@v1
126+
# Only run the action when the workflow is triggered by a pull request.
127+
if: github.event_name == 'pull_request'
128+
```
130129

131-
# This step is needed to pass the size data to the report job
132-
- name: Upload sketches report to workflow artifact
133-
uses: actions/upload-artifact@v3
134-
with:
135-
name: ${{ env.SKETCHES_REPORTS_ARTIFACT_NAME }}
136-
path: ${{ env.SKETCHES_REPORTS_PATH }}
130+
---
137131

138-
# When using a matrix to compile for multiple boards, it's necessary to use a separate job for the deltas report
139-
report:
140-
needs: compile # Wait for the compile job to finish to get the data for the report
141-
if: github.event_name == 'pull_request' # Only run the job when the workflow is triggered by a pull request
142-
runs-on: ubuntu-latest
143-
steps:
144-
# This step is needed to get the size data produced by the compile jobs
145-
- name: Download sketches reports artifact
146-
uses: actions/download-artifact@v3
147-
with:
148-
name: ${{ env.SKETCHES_REPORTS_ARTIFACT_NAME }}
149-
path: ${{ env.SKETCHES_REPORTS_PATH }}
132+
**ⓘ** A more advanced example is available in [the **FAQ**](docs/FAQ.md#workflow-triggered-by-pull_request-event).
150133

151-
- uses: arduino/report-size-deltas@v1
152-
with:
153-
sketches-reports-source: ${{ env.SKETCHES_REPORTS_PATH }}
154-
```
134+
---
135+
136+
## Additional resources
137+
138+
- [Introductory article about **arduino/report-size-deltas**](https://blog.arduino.cc/2021/04/09/test-your-arduino-projects-with-github-actions/)
139+
- [Frequently asked questions about **arduino/report-size-deltas**](docs/FAQ.md#frequently-asked-questions)
140+
- [**GitHub Actions** documentation](https://docs.github.com/actions/learn-github-actions/understanding-github-actions)
141+
- [Discuss or request assistance on **Arduino Forum**](https://forum.arduino.cc/)

‎docs/FAQ.md

+201
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# Frequently Asked Questions
2+
3+
## How can I work with sketches reports for multiple boards?
4+
5+
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.
6+
7+
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.
8+
9+
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).
10+
11+
### Size deltas report workflow triggered by `schedule` event
12+
13+
#### Sketch compilation workflow
14+
15+
```yaml
16+
on:
17+
- push
18+
- pull_request
19+
20+
jobs:
21+
compile:
22+
runs-on: ubuntu-latest
23+
24+
env:
25+
# It's convenient to set variables for values used multiple times in the workflow.
26+
SKETCHES_REPORTS_PATH: sketches-reports
27+
28+
strategy:
29+
matrix:
30+
board:
31+
# Each element in the sequence produces a matrix job:
32+
- fqbn: arduino:avr:uno
33+
# This suffix will be used to define a unique name for the sketches report artifact.
34+
artifact-name-suffix: arduino-avr-uno
35+
- fqbn: arduino:samd:mkrzero
36+
artifact-name-suffix: arduino-samd-mkrzero
37+
38+
steps:
39+
- uses: actions/checkout@v4
40+
41+
- uses: arduino/compile-sketches@v1
42+
with:
43+
enable-deltas-report: true
44+
fqbn: ${{ matrix.board.fqbn }}
45+
sketches-report-path: ${{ env.SKETCHES_REPORTS_PATH }}
46+
47+
- uses: actions/upload-artifact@v4
48+
with:
49+
# A fixed prefix on the artifact name allows the arduino/report-size-deltas action to identify the sketches
50+
# report artifacts.
51+
name: sketches-report-${{ matrix.board.artifact-name-suffix }}
52+
path: ${{ env.SKETCHES_REPORTS_PATH }}
53+
```
54+
55+
#### Size deltas report workflow
56+
57+
```yaml
58+
on:
59+
schedule:
60+
- cron: "*/5 * * * *"
61+
62+
jobs:
63+
build:
64+
runs-on: ubuntu-latest
65+
66+
steps:
67+
- uses: arduino/report-size-deltas@v1
68+
with:
69+
# This regular expression matches names of sketches report artifacts produced by sketch compilation workflow.
70+
sketches-reports-source: ^sketches-report-.+
71+
```
72+
73+
#### Overview of sketches report data flow
74+
75+
```mermaid
76+
%%{
77+
init: {
78+
'flowchart': {
79+
'curve': 'basis'
80+
},
81+
'theme': 'base',
82+
'themeVariables': {
83+
'clusterBkg': '#ffffff',
84+
'edgeLabelBackground': '#ffffff',
85+
'lineColor': '#000000',
86+
'primaryBorderColor': '#000000',
87+
'primaryColor': '#f0f0f0',
88+
'primaryTextColor': '#000000'
89+
}
90+
}
91+
}%%
92+
93+
flowchart TB
94+
subgraph main[" "]
95+
direction TB
96+
97+
subgraph compileWorkflow["<b>Sketch compilation workflow run</b>"]
98+
direction TB
99+
100+
unoJob["arduino:avr:uno<br />job"]
101+
mkrzeroJob["arduino:samd:mkrzero<br />job"]
102+
103+
unoCompile["arduino/compile-sketches<br />action"]
104+
mkrzeroCompile["arduino/compile-sketches<br />action"]
105+
106+
unoReportFile["arduino-avr-uno.json"]
107+
mkrzeroReportFile["arduino-samd-mkrzero.json"]
108+
109+
unoUpload["actions/upload-artifact<br />action"]
110+
mkrzeroUpload["actions/upload-artifact<br />action"]
111+
112+
unoArtifact["sketches-reports-arduino-avr-uno<br />artifact"]
113+
mkrzeroArtifact["sketches-reports-arduino-samd-mkrzero<br />artifact"]
114+
end
115+
116+
subgraph reportWorkflow["<b>Size deltas report workflow run</b>"]
117+
direction TB
118+
119+
reportAction["arduino/report-size-deltas<br />action"]
120+
end
121+
122+
subgraph pr["<b>Pull request</b>"]
123+
direction TB
124+
125+
comment["Size deltas report<br />comment"]
126+
end
127+
128+
unoJob --> unoCompile
129+
mkrzeroJob --> mkrzeroCompile
130+
unoCompile --> unoReportFile
131+
mkrzeroCompile --> mkrzeroReportFile
132+
unoReportFile --> unoUpload
133+
mkrzeroReportFile --> mkrzeroUpload
134+
unoUpload --> unoArtifact
135+
mkrzeroUpload --> mkrzeroArtifact
136+
137+
unoArtifact --> reportAction
138+
mkrzeroArtifact --> reportAction
139+
reportAction --> comment
140+
end
141+
```
142+
143+
### Workflow triggered by `pull_request` event
144+
145+
```yaml
146+
on:
147+
- push
148+
- pull_request
149+
150+
env:
151+
# It's convenient to set variables for values used multiple times in the workflow.
152+
SKETCHES_REPORTS_PATH: sketches-reports
153+
154+
jobs:
155+
compile:
156+
runs-on: ubuntu-latest
157+
158+
strategy:
159+
matrix:
160+
board:
161+
# Each element in the sequence produces a matrix job:
162+
- fqbn: arduino:avr:uno
163+
# This suffix will be used to define a unique name for the sketches report artifact.
164+
artifact-name-suffix: arduino-avr-uno
165+
- fqbn: arduino:samd:mkrzero
166+
artifact-name-suffix: arduino-samd-mkrzero
167+
168+
steps:
169+
- uses: actions/checkout@v4
170+
171+
- uses: arduino/compile-sketches@v1
172+
with:
173+
fqbn: ${{ matrix.board.fqbn }}
174+
enable-deltas-report: true
175+
sketches-report-path: ${{ env.SKETCHES_REPORTS_PATH }}
176+
177+
# This step is needed to pass the size data to the report job.
178+
- name: Upload sketches report to workflow artifact
179+
uses: actions/upload-artifact@v4
180+
with:
181+
name: sketches-reports-${{ matrix.board.artifact-name-suffix }}
182+
path: ${{ env.SKETCHES_REPORTS_PATH }}
183+
184+
# When using a matrix to compile for multiple boards, it's necessary to use a separate job for the deltas report
185+
report:
186+
needs: compile # Wait for the compile job to finish to get the data for the report
187+
if: github.event_name == 'pull_request' # Only run the job when the workflow is triggered by a pull request
188+
runs-on: ubuntu-latest
189+
190+
steps:
191+
# This step is needed to get the size data produced by the compile jobs
192+
- name: Download sketches reports artifacts
193+
uses: actions/download-artifact@v4
194+
with:
195+
# All workflow artifacts will be downloaded to this location.
196+
path: ${{ env.SKETCHES_REPORTS_PATH }}
197+
198+
- uses: arduino/report-size-deltas@v1
199+
with:
200+
sketches-reports-source: ${{ env.SKETCHES_REPORTS_PATH }}
201+
```

0 commit comments

Comments
 (0)