Skip to content

Commit 66a0fec

Browse files
psiddhpsiddh
authored
examples/arduino: Release Management of Arduino ET (pytorch#22002)
The published library is generated from this directory, so releasing it is a procedure rather than a button, and the parts that matter are the ones that have already gone wrong. Publishing must delete the generated paths before copying, because cp only adds and overwrites: a stale zephyr.cpp survived a regeneration and shipped alongside the arduino_pal.cpp meant to replace it, giving two definitions of every et_pal_* symbol. The tag must wait until the release commit is on main; tagging first left a tag on a commit no branch contained, twice. Verification is four things, and the last is the one that counts. Compiling proves very little here - every packaging failure worth finding in this library compiled cleanly first - so a release flashes a board and reads the output. verify_models.py catches a model exported against a different ExecuTorch than the library was built from, which otherwise surfaces as InvalidProgram deep inside execute. arduino-lint runs as an update rather than a submission now that the name is in the index. And the version has to differ from anything previously indexed or Library Manager drops the release without saying so. Authored with Claude Code (Opus 5).
1 parent 8b5da54 commit 66a0fec

2 files changed

Lines changed: 168 additions & 0 deletions

File tree

‎examples/arduino/README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -342,6 +342,12 @@ python export_model.py --checkpoint examples/KeywordSpotting/model.pth \
342342
--output /tmp/kws.h
343343
```
344344

345+
### Releasing
346+
347+
[RELEASING.md](RELEASING.md) is the checklist for cutting a version of the
348+
published library: what to verify, how to publish without leaving stale files
349+
behind, and what has gone wrong before.
350+
345351
### Bumping the pin in executorch-arduino
346352

347353
The published library records the commit it was generated from in

‎examples/arduino/RELEASING.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# Releasing the Arduino library
2+
3+
The published library at
4+
[meta-pytorch/executorch-arduino](https://github.com/meta-pytorch/executorch-arduino)
5+
is generated from this directory. Everything under `src/`, `examples/` and
6+
`extras/` comes out of `build_arduino_library.sh` and is never hand-edited —
7+
make the change here, then regenerate.
8+
9+
Library Manager indexes new git tags hourly, so pushing a tag publishes the
10+
release.
11+
12+
## 1. Make your changes
13+
14+
Edit anything under `examples/arduino/` in this repository and land it as a
15+
normal pull request. Then release from a clean checkout of `main`.
16+
17+
## 2. Bump the version
18+
19+
```bash
20+
cd examples/arduino
21+
./build_arduino_library.sh --bump minor # major | minor | patch
22+
```
23+
24+
Minor for new public API such as `ETModel.h`, patch for fixes. The version must
25+
differ from every previously published one or Library Manager drops the release.
26+
27+
## 3. Build
28+
29+
The exporter must be the same ExecuTorch as the runtime, or the shipped models
30+
will not match the library:
31+
32+
```bash
33+
./install_executorch.sh # from the repository root
34+
cd examples/arduino && ./build_arduino_library.sh
35+
```
36+
37+
## 4. Verify
38+
39+
```bash
40+
# every example compiles -- static link mode is required
41+
for s in arduino_lib/ExecuTorch/examples/*/; do
42+
arduino-cli compile --fqbn arduino:zephyr:unoq:link_mode=static "$s"
43+
done
44+
45+
# shipped models match the library that will run them
46+
python verify_models.py arduino_lib/ExecuTorch
47+
48+
# Library Manager's own rules ("update", not "submit" -- the name is indexed)
49+
cd arduino_lib/ExecuTorch
50+
arduino-lint --project-type library --library-manager update --compliance strict
51+
cd -
52+
```
53+
54+
Then flash an Uno Q and run all three examples. Compiling is not enough on its
55+
own; failures here reach the board before they reach the compiler.
56+
57+
## 5. Copy into the published repository
58+
59+
Delete the generated paths first — a plain `cp` leaves behind files the build no
60+
longer emits:
61+
62+
```bash
63+
cd <executorch-arduino>
64+
git rm -r --quiet src examples extras library.properties executorch_pin.txt
65+
cp -r <executorch>/examples/arduino/arduino_lib/ExecuTorch/. .
66+
git add -A
67+
```
68+
69+
`README.md`, `CHANGELOG.md`, `LICENSE` and `.github/` belong to that repository
70+
and are not generated.
71+
72+
## 6. Check what you are about to publish
73+
74+
```bash
75+
grep ^version= library.properties # the version you bumped to
76+
cat executorch_pin.txt # matches: git -C <executorch> rev-parse HEAD
77+
ls src/executorch/runtime/platform/default/ # exactly one .cpp
78+
git status --short | grep '^D ' # deletions are expected, not surprising ones
79+
```
80+
81+
## 7. Open a release pull request
82+
83+
The repository requires pull requests, so push a branch:
84+
85+
```bash
86+
git push origin main:release-<version>
87+
```
88+
89+
Open it against `main` and merge.
90+
91+
## 8. Tag the merged commit
92+
93+
Tag last. A tag pushed before the release commit is on `main` points at a commit
94+
no branch contains, and the fix is to delete a published tag:
95+
96+
```bash
97+
git fetch origin && git checkout main && git reset --hard origin/main
98+
grep ^version= library.properties # confirms the merge landed
99+
git tag v<version>
100+
git push origin v<version>
101+
git rev-parse v<version> HEAD # both must print the same SHA
102+
```
103+
104+
If a tag already exists on the wrong commit, move it:
105+
106+
```bash
107+
git push origin :refs/tags/v<version> # delete on the remote
108+
git tag -d v<version> # delete locally
109+
git tag v<version> # recreate on the current HEAD
110+
git push origin v<version>
111+
```
112+
113+
## 9. Write the release notes
114+
115+
Draft a release against the tag at
116+
`https://github.com/meta-pytorch/executorch-arduino/releases/new?tag=v<version>`.
117+
118+
Arduino library releases are short. Use GitHub's **Generate release notes** for
119+
the `What's Changed` list, then write a few lines above it:
120+
121+
```markdown
122+
<One or two sentences: what this release is for.>
123+
124+
**Upgrading:** <anything a user must change -- an include that moved, an arena
125+
that needs raising, a board core version. This goes first, not last.>
126+
127+
## Highlights
128+
* <User-visible change, naming the API or #define involved>
129+
* <Board or core support, by marketing name>
130+
* <Footprint change, if measured>
131+
132+
## What's Changed
133+
<generated>
134+
135+
**Full Changelog**: .../compare/v<previous>...v<version>
136+
```
137+
138+
Title the release with what a user cares about, for example
139+
`v0.2.0 — ETModel helper and Arduino platform layer`.
140+
141+
Add a matching `CHANGELOG.md` entry in that repository's existing format.
142+
143+
## 10. Confirm it indexed
144+
145+
Indexing takes an hour or two:
146+
147+
```bash
148+
arduino-cli lib update-index
149+
arduino-cli lib search ExecuTorch # should list the new version
150+
```
151+
152+
Rejections are silent. If the version has not appeared after a few hours:
153+
154+
```
155+
http://downloads.arduino.cc/libraries/logs/github.com/meta-pytorch/executorch-arduino/
156+
```
157+
158+
## Record what you tested against
159+
160+
Board core versions change what the library needs — an arena size that worked on
161+
one core has failed on the next. Note the core version in the release notes, and
162+
keep the pin in CI matching it.

0 commit comments

Comments
 (0)