Yonto Player ships often, and an Android install updates only when the new APK meets the platform's rules. So the way I version and cut a release is a short list of rules, each one with a reason behind it.
This is the list. It is not clever, and that is the point of it.
One version pair, in one file
Every app module reads its version from a single pair in gradle.properties. This is a simplified sketch of it, with made-up numbers and generic names:
# gradle.properties (simplified sketch, made-up numbers)
# The release's version, read by every app module.
app.versionCode=12
app.versionName=1.4.2
versionName is what people read: semantic, MAJOR.MINOR.PATCH, and the git tag is v plus it. versionCode is what Android reads. The TV app and the phone app both take the same pair, so a release bumps both at once and the two stay in step.
PATCH goes up by one on every release
The usual bump is PATCH, by exactly one. A release is usually a fix or a polish, and it should look small in the version too.
MINOR and MAJOR move only when I decide a release marks a step, and each one resets the parts below it to zero. A change that merely feels big does not move them.
The plugin contract has a version of its own, and it does not shape the app's version. They answer different questions, so each keeps its own number.
A version code that only goes up
Android requires the versionCode of an update to be higher than the installed one. So the code goes up by one on every release, whatever part of the name moved.
It is a counter and not a value computed from the name. The next release is always the last one plus one, and the name can follow whatever semantic rules it likes.
A patch that must not carry main
Sometimes the fix has to go out without the rest of main. For that, the patch is cut from the last tag, not from main:
# tag-to-branch flow for a patch (simplified sketch, made-up versions)
git switch -c release-1.4.3 v1.4.2 # branch off the last tag
git cherry-pick <fix-commit> # the fix, once it has merged on main
# bump the version pair, add the changelog entry, build and release from here
git tag -a v1.4.3 -m "Release 1.4.3"
# then a PR to main records the version pair and the changelog entry
The fix lands on main first and is cherry-picked second, so main keeps it too. The last step writes the version back to main, so the next build cut from there gets a versionCode higher than the patch's. The branch builds with the module layout and asset names the tag had, so what it produces is the old shape plus the fix.
Pre-releases and betas
A beta is tagged with a suffix on the next target version, v1.5.0-beta.1, and published as a GitHub pre-release. Its versionCode goes up by one, like any other release.
The app has a Beta updates option in Settings → About on Android (released in 5.4.9) that lets an install receive pre-release builds. The plain "latest release" lookup skips pre-releases.
Two APKs per release
A release carries two APKs, one for the TV app and one for the phone app, named Yonto-AndroidTV-vX.Y.Z.apk and Yonto-Phone-vX.Y.Z.apk, as the public releases page shows. Because one release serves both apps, a TV hotfix is a single tag with both APKs, the phone's rebuilt unchanged. After publishing I read the release's asset names back from GitHub to confirm they are the two I expect.
A changelog in the viewer's terms
A changelog is written by hand, in the terms of the person holding the remote and not in the code's, and a release is not cut until its entry exists. git log is the raw material for it, not the entry: a commit message says what changed in the code, and a viewer wants to know what is different when they sit down to watch.
The entries are grouped by platform, under a heading of one fixed shape:
## 1.4.3 (version and date format as a sketch)
### All apps
- (what changed, in the viewer's words)
### TV
- (...)
### Phone and tablet
- (...)
The site's build checks the release heading, ## X.Y.Z — date, and refuses to build on any other shape.
The order I cut a release in
- Bump the version pair and write the changelog entries on a branch that merges into
main. - Build both APKs from
mainat that merge commit, so the file is what the tag names. - Run the full verification line on that commit.
- Check each APK's reported
versionCode,versionNameand package withaapt dump badging. - Install the previous release, install the new APK over it, and look that what the old install held is still there. The update path is the thing that has to work, so that is the path I test.
- Tag, push the tag, publish.
- Ask GitHub for the latest release and read the asset names back.
Releases are cut by hand, on purpose. Each step can be followed from the page, and the last one confirms the result from the outside, the way an install will see it.
What to take from it
- Make the code a counter, separate from the name.
- Make the usual bump the boring one, and the larger ones a decision.
- When a patch must not carry the rest of
main, branch from the tag, cherry-pick, and write the version back. - Write the changelog in the reader's words, and let the build check what it can.
Read more
The changelog shows the shape in practice, the install guide for Android TV shows what the TV's APK is for, and the developer docs describe the plugin contract and its own version. The SDK and CLI are in the plugins repo.
Top comments (0)