Skip to content

12. Releases

What you see

When a newer build is out, a card on the bare map says "Vela 0.4.1830 is available", with Not now and Update and a fold that shows what changed. Update downloads the file, then Android's install dialog takes over. The first launch of the new build shows its release notes once, in a "What's new" dialog.

Settings > About has a Check for updates on launch switch (on by default), the Update channel choice (Stable, Nightly or Canary), a Check for updates button, a row that reopens What's new, a switch that turns that dialog off, and a line saying which app Android recorded as the installer.

Obtainium and Vela's own F-Droid repository deliver the same builds. Every channel and source carries APKs signed with the same key, so moving between them never needs a reinstall.

Where the data comes from

Every build is a GitHub release on PimpinPumpkin/Vela, built by GitHub Actions from this repository. There is no update server.

Channel Release Tag Cut by
Canary One prerelease, replaced on each push canary ci.yml, on a push to the canary branch
Nightly One prerelease a day when main has moved v0.5.<run> ci.yml, daily at 10:30 UTC or on dispatch
Stable The newest nightly, made a full release The nightly's tag promote-stable.yml, Mondays 16:00 UTC or on dispatch

release.yml ("Release now") does both by hand in one run, for a build that should not wait: channel nightly cuts a nightly from main now, and stable cuts it and promotes that same build. It builds nothing: it dispatches ci.yml, waits for it, and calls promote-stable.yml with the tag that run cut. It runs only on main, stops if main moves under it, and takes an optional sha that main must be at. It ends by dispatching fdroid-repo.yml: work done with the workflow's own token starts no other workflow, so the index would not rebuild on its own.

The F-Droid repository is a copy of the same APKs, served from GitHub Pages at https://pimpinpumpkin.github.io/Vela/repo. The full list of rules and constants is SPEC section 15.

How it is decided

Three channels

A push to main or canary builds, tests and uploads the APK as a workflow artifact. A push that changes only docs paths (paths-ignore in ci.yml) starts no run. A push to main never makes a release.

canary is the working branch. Each push deletes the canary release and creates it again on the pushed commit, which keeps it at the top of the releases page. The download URL and the updater's lookup do not change, and the few seconds of 404 during the swap read as nothing newer. A build that a newer push to canary has overtaken does not publish: the newer build does. The tag is not a v0.* tag, so the nightly, stable, prune and F-Droid queries never see it. It never changes either, so the version is in the notes:

Canary branch.

versionName: 0.5.2420-canary
versionCode: 38220

Latest change: <newest user-facing commit subject>

The nightly job publishes only if main has moved since the newest v0.[0-9]* tag. The cron also skips a main that moved only in files that never reach the app (docs, the website, repo metadata; scripts/app-changed.sh, the same list as the push filter), so the weekly reach snapshot cuts no nightly. A manual dispatch of ci.yml cuts whenever main moved (force recuts the same commit) and is how a fix ships before the next cron. The title ends in "nightly" and the notes open with "Nightly build.", so that someone reading them in the app can tell the channel.

The promotion compares the newest prerelease and the newest full release whose tags match ^v0\.[0-9]+\.[0-9]+$, and stops unless the nightly has the higher run number. It then edits the nightly in place: title Vela <version>, prerelease off, marked Latest, notes regenerated to cover everything since the previous stable. Nothing is rebuilt.

Stables are never deleted. They are the changelog and the bisect range, and a deleted release loses its download count. Nightlies keep the newest 30, and the prune deletes older ones with their tags.

Version names and codes

ci.yml derives both from github.run_number:

versionName = 0.5.<run>              (canary: 0.5.<run>-canary)
versionCode = (2000 + <run>) * 10    plus a chip digit, 0 for the all-in-one APK

The minor is a name: 0.4 until the stable of 2026-10-08, 0.5 from it. The run number is what orders releases, in the tag, in the updater and in the version code, so a 0.5 build is an upgrade from every 0.4 one.

The counter counts every run of ci.yml, pushes and pull requests included. Nightly numbers therefore have gaps, and all three channels share one rising versionCode. Switching channel in either direction is an upgrade to the installer.

  • Releases are cut inside ci.yml. Another workflow's counter would start at 1 and send the code backward.
  • The versionName is plain semver so that Obtainium can compare it.
  • Never name a release v0.5.0. The updater takes the run number from the tag, reads code 2000 and never offers it.

The updater compares on the older scale 2000 + run. legacyCode (update/ApkChoice.kt) divides a code of 20000 or more by ten, which drops the chip digit: 38222 and 38220 both read 3822.

One APK per chip type

With the repository variable ABI_SPLITS set to true, a release carries one APK per chip type (vela-maps-arm64.apk, -armv7.apk, -x86.apk, -x86_64.apk) and the all-in-one vela-maps-all.apk. The switch is still off (ROADMAP), so a release carries one APK.

  • ApkChoice.pick walks Build.SUPPORTED_ABIS in the phone's order and takes the first asset ending in -<chip>.apk, else the first APK with no chip in its name.
  • Each chip APK adds a digit to the versionCode: armv7 1, arm64 2, x86 3, x86_64 4. Moving from the all-in-one APK to a chip APK of the same build is then an upgrade, and an F-Droid index gets the distinct code it needs for every APK.
  • GitHub lists assets by name, and updaters older than ApkChoice take the first .apk. vela-maps-all.apk sorts first, so an old build keeps getting a file that runs on every chip. The switch can go on once a build with ApkChoice has been the stable for a few weeks.
  • An arm64 phone then downloads 74.3 MB in place of 108.4.

Release notes

Notes are the commit subjects since the previous release, one line each, from scripts/changelog.sh. They appear on the release page, in Obtainium, in the update card and in the What's new dialog, so a subject is written as a plain sentence about what changed for the user.

A nightly lists the commits since the previous v0.* tag, a stable those since the previous stable, and canary only the newest subject. A commit is left out when it touches only docs paths, when it changes only comments or blank lines, or when its subject starts with Docs:. A docs sweep would otherwise read as a feature.

The app shows notes through plainReleaseNotes, which strips the Markdown marks and keeps the first 24 lines. It drops the notes' own "What's new in " heading, which the dialog and the update card already show as their title, and stops at "Everything since", so a stable's hand-written list is shown whole and the commits under it are left to "Full notes". A stable's generated list covers a week, can run past 24 lines, and reads like a git log. So a stable's notes lead with a short hand-written list of the main user-facing changes, above the generated one. The promotion cannot write that list, but it can be handed it: the whats_new input of release.yml and promote-stable.yml puts it under "What's new in ", and the generated list follows under "Everything since ". A promotion run without it (the Monday cron) leaves the notes to be edited by hand (gh release edit v0.5.<run> --notes-file).

The in-app updater

SelfUpdater.check runs at launch and from the Check for updates button. The launch check needs its switch (self_update_check) and runs at most once in 20 hours.

  • Stable reads releases/latest. The promotion marks each stable Latest and the data releases are prereleases, so Latest is the newest stable.
  • Nightly lists the app tags through git/matching-refs/tags/v0., once per check, and takes the highest of the newest three runs that has a published release, nightly or stable. A release is fetched by the tag name the list gave (appReleaseTags), so a new version line such as v0.5.<run> needs no change in the app.
  • Canary reads releases/tags/canary and the version lines in its notes, and also runs the nightly check. The nightly is taken only when its code is higher and it holds canary's commit, so a canary that main has caught up with strands nobody. A nightly is cut from main, and a Weblate merge or the weekly stats commit gives it a higher run number than a canary that is ahead of main: by code alone it would replace canary's fixes with an older main. The check is one compare/<nightly commit>...<canary commit> request, made only when the nightly's code is higher, and it counts when the answer is behind or identical. It asks for page 2 at one commit a page, which leaves out the file list: about 10 KB, where page 1 for a canary ahead of main carried its whole diff (450 KB measured). A failed compare keeps canary, and so does a canary release that cannot be read, which offers nothing: each push deletes it before making the new one.

The updater never fetches the releases list. The data releases carry about 450 assets each, and a check that listed them downloaded 4 to 9 MB. Every check logs one line under VelaUpdate, and the canary compare one more.

An update is offered when its code is above the installed one. A failed check returns nothing and the launch does not wait for it. Not now stores the offered code in update_dismissed_code, and the launch check stays quiet until a higher code appears. The button ignores the stored code.

For stable and nightly the card also shows the notes of skipped releases: up to HISTORY_MAX_RELEASES (8) between the installed build and the offered one, each under its version.

Download and install:

  • The APK that ApkChoice picked is saved in filesDir/updates/, and anything else there is deleted.
  • The download client has no call timeout, because the shared client's 12 s limit would cut the body off. The download runs under a foreground service (MapViewModel.downloadLaunch) and can be canceled.
  • ApkCheck accepts the file only if it starts with the zip bytes PK, has the size the release states, and matches the SHA-256 GitHub publishes for the asset when there is one. A file that fails is deleted.
  • A file that passed is kept until a newer update replaces it. Android's install prompt goes away when the screen locks, and the next tap on Update reuses the file after checking it again.
  • The APK goes to the system installer through the FileProvider. Android requires the same package and the same signing certificate, and the user confirms.

The updater holds the update back when Android records Play as the app that installed Vela or started the install (InstallSource.setForCar). A tool sets that record so that Android Auto will list Vela, and a self-install would replace it. A dialog offers Save the file, for that tool, or Update anyway. Chapter 10 explains the gate.

What's new

ui/WhatsNew.kt compares the build's versionName with last_seen_version at launch. With no stored version, an unfinished welcome screen or the dialog switched off, it stores the current version and shows nothing. With a new version it fetches the build's own release, releases/tags/v<versionName> or releases/tags/canary, and shows the notes once, after any other one-time prompt.

Nothing is bundled in the APK, so the dialog shows what the release body says that day. A failed fetch leaves the version unseen, and the next launch tries again.

Obtainium

Obtainium follows the GitHub releases: the latest full release by default, which is the weekly stable, and nightlies with "include prereleases" on. It reads the version from the tag, and the canary tag never changes, so canary users take the in-app updater or download the APK.

Obtainium reads only the first hundred releases. The per-region data releases are therefore created where GitHub sorts them last (SPEC section 7.6).

The F-Droid repository

fdroid-repo.yml builds a signed F-Droid repository from the releases. It is Vela's own repository, because f-droid.org builds every app from source and Vela bundles prebuilt libraries. FDROID.md is the user guide.

  • It serves the newest stable, plus the newest nightly when that is ahead.
  • The build reads the versionCode off each stable APK and writes the highest into the app metadata as CurrentVersionCode. Clients suggest versions up to that code and treat higher ones as unstable, so a default user updates weekly and the nightly reaches only someone who turns on unstable updates for Vela.
  • It runs after a nightly cut or a promotion through workflow_run, because a release created by CI's own token fires no release event for other workflows.

The signing certificate

APKs are signed with the release keystore, which is outside the repository and reaches CI as repository secrets. Without them, as in a fork's CI, the release build is signed with the debug key and cannot update a real install. If the keystore were lost, no installed copy could be updated again.

The certificate's SHA-256 is in the README and in FDROID.md. Check an APK against it with apksigner verify --print-certs. The F-Droid index is signed with a separate key, and the fingerprint in the repository address belongs to that key.

The other releases are data hosting

Every release whose tag does not start with v0. holds files the app or the build downloads: the datasets in chapter 2 and the build runtimes (tts-runtime, obf-runtime, cronet-runtime). The files exist nowhere else. These releases are prereleases too, so a cleanup of old prereleases matches them.

Anything that deletes, edits or picks releases selects by the tag pattern v0.*, never by "prerelease" or by age. A prune that selected old prereleases deleted four data releases, and offline downloads failed until the data was rebuilt. A promotion that took the newest prerelease of any tag promoted a data release, and releases/latest then had no APK for the updater or the F-Droid build.

ci.yml, promote-stable.yml and fdroid-repo.yml read the app's releases from scripts/app-releases.sh, which pages through the whole list and keeps the tags that start with v0., newest first by run number. Among hundreds of releases, a fixed --limit window can hold no app release at all. The script asks GraphQL for the tag, the prerelease flag and the creation time only, which takes 2.5 s for about 500 releases. The REST listing returns every asset of every release: a page of 100 is 25 MB and takes 9 s, at the edge of GitHub's 10 s limit.

Local builds

Without the CI properties a build is versionName 0.3.0, versionCode 1. Keep a hand-set code below 1000, so that a phone that ran a local build is never ahead of the release line.

To test the updater without touching the installed app, build a second package with a high code (-PappId=app.vela.dev -PappVersionCode=37000), check for updates, and look for installed=3700 under VelaUpdate.

Limits

  • A stable can be hours old. The promotion takes the newest nightly at Monday 16:00 UTC, the nightly job runs at 10:30, and nothing checks the build's health. Keeping a bad nightly out of stable means getting a fixed one out before the promotion.
  • Moving from canary or nightly to stable offers nothing until stable passes the installed build. The updater never offers a lower code.
  • A canary build's What's new can describe a newer canary, because the release it reads is replaced on every push. A nightly pruned before its first launch has no release, so its dialog never shows and the app asks again at each launch.
  • The notes of skipped releases cover the newest 8 tags in the gap, counted before the other channel's releases are filtered out, so on stable the nightlies in between take most of them. A nightly user's list leaves out a release that has since been promoted.
  • What Obtainium does with five APKs on one release is untested. A user may need to set a filter once the per-chip switch is on.
  • F-Droid installs are counted nowhere. Pages serves the files with no counter.