Skip to content

Commit 90ad27d

Browse files
per1234per1234
committed
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.
1 parent 677622c commit 90ad27d

File tree

2 files changed

+148
-0
lines changed

2 files changed

+148
-0
lines changed

‎README.md

+7
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,12 @@ jobs:
104104
path: sketches-reports
105105
```
106106

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+
107113
### Workflow triggered by `pull_request` event
108114

109115
```yaml
@@ -157,5 +163,6 @@ jobs:
157163
## Additional resources
158164

159165
- [Introductory article about **arduino/report-size-deltas**](https://blog.arduino.cc/2021/04/09/test-your-arduino-projects-with-github-actions/)
166+
- [Frequently asked questions about **arduino/report-size-deltas**](docs/FAQ.md#frequently-asked-questions)
160167
- [**GitHub Actions** documentation](https://docs.github.com/actions/learn-github-actions/understanding-github-actions)
161168
- [Discuss or request assistance on **Arduino Forum**](https://forum.arduino.cc/)

‎docs/FAQ.md

+141
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
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+
```

0 commit comments

Comments
 (0)