diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5a86af3..0f64e4c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,6 +25,10 @@ Start reading the Lua Telemetry code and you'll get the hang of it: Please be sure to test your changes before creating a pull request. While your changes will be tested by others, it's appreciated when changes work on the first try. +## Releasing + +If you're cutting a release, see [RELEASING.md](RELEASING.md) for the build/tag/publish process. + Thanks, [Tim Eckel](https://github.com/teckel12), Señor Lua Telemetry Coder diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000..2570b9f --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,164 @@ +# How to Release Lua Telemetry + +This documents the release process for maintainers. It reflects what actually +builds and ships today (`Makefile` + `.github/workflows/`), not the legacy +`release` shell script at the repo root, which predates the current +`WIDGETS/`-based layout and is no longer used by CI or by the release +workflow. + +## Versioning + +There is a single source of truth for the version number: the `VERSION` +string in `src/SCRIPTS/TELEMETRY/iNav.lua`: + +```lua +local VERSION = "2.4" +``` + +This is what the widget displays on the transmitter, and it's also what the +`Makefile` reads to name build output (`make print-version`, or +`grep VERSION src/SCRIPTS/TELEMETRY/iNav.lua`). There is no separate +version file — bumping this string *is* bumping the version. + +**Bump this before tagging, not after.** If you tag first and bump later, +the tagged commit's source disagrees with what ships in the zip asset built +from a later commit (this happened with the 2.4 release — see "Lessons from +the 2.4 release" below). + +### Tag naming + +Use `vX.Y.Z` (three-part semver, `v` prefix) — e.g. `v2.4.0`. Past tags have +been inconsistent (`v2.2.0`, `v.2.3.0` with a stray dot, and `2.4` with no +prefix at all), which is exactly why `release.yml`'s tag trigger currently +has to match more than one pattern (see below). Stick to `vX.Y.Z` going +forward so the trigger doesn't need further patching. + +## What gets built + +`make dist` and `make dist-lua` are two independent targets — `dist` does +not depend on `dist-lua`, so building one does not build the other: + +- **`make dist`** — compiles every `.lua` file under `src/SCRIPTS/` and + `src/WIDGETS/` to stripped bytecode (`luac -s`) and zips it as + `dist/LuaTelemetry_v.zip`. This is what most users install. +- **`make dist-lua`** — zips the raw, uncompiled `src/` tree as-is, no + compilation, as `dist/LuaTelemetry_v_lua.zip`. Needed for + EdgeTX 2.11rc1+ (which broke loading precompiled Lua) and for the + simulator. + +Both files are added to `src/SCRIPTS/TELEMETRY/iNav/*.lua` etc. via +wildcard, so **new view files (e.g. `tx15.lua`, `tx16s.lua`) are picked up +automatically** — no Makefile changes needed when adding a new screen +layout. + +To build both locally: + +```bash +make dist dist-lua +``` + +Both zips land in `dist/`. + +## Automated builds + +- **`.github/workflows/ci.yml`** — runs on every PR and push, builds both + zip variants (`make dist dist-lua`) as a CI artifact. Doesn't touch + releases. +- **`.github/workflows/release.yml`** — runs on a tag push matching `v*` or + a bare `X.Y*` numeric tag (`[0-9]+.[0-9]+*`), builds both zips, and + uploads them to the GitHub release matching that tag name via + `svenstaro/upload-release-action`. + +**A release only gets assets automatically if the tag matches one of those +two patterns.** If you tag something that doesn't match (e.g. a typo, or +some future new format), the workflow silently never fires — GitHub won't +warn you, the release will just have zero assets. Always check +`gh release view --repo iNavFlight/OpenTX-Telemetry-Widget` after +tagging to confirm assets showed up (see checklist below). + +## Release procedure + +1. **Bump `VERSION`** in `src/SCRIPTS/TELEMETRY/iNav.lua` and merge that to + `master` (PR, same as any other change). +2. **Tag the merged commit** with `vX.Y.Z`: + ```bash + git tag vX.Y.Z + git push origin vX.Y.Z + ``` + Or via `gh` without a local checkout: + ```bash + gh release create vX.Y.Z --repo iNavFlight/OpenTX-Telemetry-Widget \ + --target --title "vX.Y.Z " \ + --generate-notes + ``` +3. **Wait ~30s, then verify the workflow ran and assets attached:** + ```bash + gh run list --repo iNavFlight/OpenTX-Telemetry-Widget --workflow=release.yml --limit 1 + gh release view vX.Y.Z --repo iNavFlight/OpenTX-Telemetry-Widget + ``` + Confirm both `LuaTelemetry_v.zip` and + `LuaTelemetry_v_lua.zip` are listed as assets. +4. If assets are missing, the tag likely didn't match the trigger patterns, + or the workflow failed. Check `gh run list` for a failed/missing run, + fix (see Troubleshooting), and re-push the tag or manually build+upload: + ```bash + make clean-obj clean-zip + make dist dist-lua + gh release upload vX.Y.Z dist/*.zip --repo iNavFlight/OpenTX-Telemetry-Widget + ``` + +## Release Notes + +Release notes should describe what has changed, from the point of view of what users will want to know. They should describe how a new feature can be used or how a change affects users, as opposed to the details of how it is implemented. + +Be sure to point out changes which have backwards compatibility changes or would surprise experienced users. + +The release notes should also describe the two zip files provided, using text such as the following: +``` +Two Zip files are provided: + +LuaTelemetry v2.3.0_lua.zip : Source LUA, compiles on the device, may be required in the simulator. Also for EdgeTX 2.11rc1 and later. + +LuaTelemetry_v2.3.0.zip : Compiled LUA, should work on all radios (prior to EdgeTX 2.11rc1, which unfortunately breaks pre-compiled Lua). +``` + +## Troubleshooting + +**Tag was pushed pointing at the wrong commit (e.g. before a needed +version-bump or fix commit landed).** You can move a tag after the fact by +updating the underlying ref, as long as the release has no assets yet that +depend on the old target: +```bash +gh api -X PATCH repos/iNavFlight/OpenTX-Telemetry-Widget/git/refs/tags/vX.Y.Z \ + -f sha="" -F force=true +``` +Moving the ref this way re-fires the tag-push event, so `release.yml` will +run again against the new commit automatically. + +**`git push` denied with 403 even though `gh api .../permissions` shows full +push access.** A restricted `GITHUB_TOKEN` env var can pin `git`/`gh` to a +fine-grained PAT that blocks raw git push while still reporting full +permissions via the API. This is intentional (limits unattended agent +actions) — don't work around it without asking whoever is driving the +release first, every time, even if they approved it earlier in the same +session. + +## Lessons from the 2.4 release + +The `2.4` release was originally tagged and published with **zero assets**, +and the reasons compound into the process above: + +- The tag `2.4` didn't match the old `release.yml` trigger (`v*` only), so + the workflow never ran. +- Even if it had matched, the workflow only ran `make dist` — the + `_lua.zip` asset (present on prior releases) had never been automated; + someone had to build and upload it by hand every time. +- The `VERSION` string was never bumped before tagging, so the source at + the tagged commit still said `2.3.0`. +- The tag was created before the version-bump/workflow-fix PR was merged, + so it had to be moved to the correct commit afterward (see + Troubleshooting above). + +All four are now fixed: `release.yml` matches both tag conventions, builds +both zips, and this document exists so version-bump-before-tag isn't +rediscovered the hard way again.