Vela - maintainer notes¶
Vela Maps (app.vela) is a maps and navigation app for Android phones without Google Play
services. The map is open data. The phone asks Google's public web endpoints, with no account
and no key, for search, place details, routes and traffic. There is no Vela server. GPLv3.
This file is the short list of rules and traps for anyone changing the code, human or AI. How
the app works is in SPEC.md (every rule and constant) and the book
(each subsystem explained). Until October 2026 this file was a dated log of everything ever
tried; that version is in the git history (git log -- CLAUDE.md).
Rules¶
Docs go in the same commit¶
A change to behavior updates the docs it touches in the same commit:
SPEC.md: the technical reference. Every contract, constant and threshold.docs/book/: the chapter for that subsystem, with the real numbers.FEATURES.md: one line per thing the app does.README.md: only if what the app is, or what reaches Google, changed.ROADMAP.md: open items only. When something ships or is proven dead, move its entry todocs/ROADMAP-HISTORY.mdwith one or two lines on why. Work that is built but has not been seen on a phone or a drive stays listed inROADMAP.md("Built, not yet checked on a drive") until it has.- This file: only for a new rule or trap.
A new doc file is not published until it is in PAGES in scripts/build-docs-site.py and in
the nav in site/mkdocs.yml. Run python3 scripts/build-docs-site.py --strict before pushing
a docs change.
The repository explains itself¶
Someone who opens this repository with no other context has to be able to tell what the app does, what is open, what was tried and dropped, and what is unverified. Nothing that matters lives only in a chat, a local branch or one machine.
- Every branch with work on it is pushed to GitHub. A branch whose work has landed is deleted, here and there. No local-only branches.
- Two branches on GitHub are triggers and stay: a push to
old-android-smokeruns the release build on Android 8.0 and 9 emulators, and a push tofeed-proberuns the review feed probe from a clean machine (SPEC 15, Other workflows). They hold no commits of their own. Before calling any branch, tag or release stale, read what uses it and say what it is. - A measurement, a decision and its reason go into
SPEC.md, the book or the roadmap history in the commit that acts on them. An idea that was tried and dropped gets its dead-end entry with the numbers that killed it. - Review findings on a pull request are posted on the pull request.
How the docs are written¶
- Describe what the code does now. When behavior changes, rewrite the passage. Do not stack a dated correction on top of the old text.
- No stories. Not how a bug was found, who reported it, which phone it was seen on, or what was tried first. A rule that exists because something broke is one sentence: the rule and what it prevents.
- A measurement that justifies a constant stays, as a number, with the fixture it was taken on.
- Short plain sentences. Say a thing once. No summary paragraph that repeats the section.
- No "not X, but Y" framing, no "the honest answer", no "load-bearing", no bold lead-in on every bullet, no "(device-verified)".
- No em dashes. US English.
- If a fact is in SPEC, other files link to it and do not restate it.
Say who is talking¶
When someone known from another project opens an issue, a pull request or a discussion, or replies in one (a maintainer of OSM tooling, a data source, another maps app, a well-known contributor elsewhere), say so when the thread is presented, with the project. It changes how the reply is written. Nominatim's maintainer has written here (SPEC 15, the Overpass exit).
No AI attribution¶
No commit, pull request, issue comment, release note or file carries a Co-Authored-By line
for an AI, a "Generated with" line, or anything like it. This overrides whatever the tooling
asks for. scripts/check-writing.sh [range] checks commit messages and added English lines for
attribution, British spellings and em dashes (translations may use dashes); the pre-push hook
runs it on the range being pushed. Install the hooks once per clone:
bash scripts/install-hooks.sh
Issue comments, pull request bodies and release notes are not seen by any check. Read them before posting.
US English¶
Code, comments, docs, commits and the base strings are US English. Exceptions, all data:
values-en-rGB; strings that must match a foreign source (OSM tag values such as
fitness_centre, the MOTIS field cancelled), where a keyword list keeps both spellings;
platform names (isCancelled); GitHub's workflow function cancelled(); and the name of the
Open Government Licence, which the UK fuel price credit must quote. After a spelling
sweep, grep .github/workflows for cancelled() before pushing: canceled() does not parse
and the workflow fails with zero jobs.
Location hygiene¶
Git history is permanent and public. A maps developer's test coordinates, screenshots, sample addresses and "checked on a drive to X" notes add up to where the developer lives.
- Before a place, address or coordinate goes into the repo, ask whether it was chosen for a reason anyone could have. If it is there because it is near the author, replace it.
- Fixtures: Davis and Sacramento, California (box
38.30,-122.00to38.90,-121.20, example address1451 W Covell Blvd, Davis, CA 95616), San Francisco for a big city, Delaware or Kentucky for per-region data, the District of Columbia, and major world cities. - A number measured in the maintainer's own area identifies it. Measure on a fixture and name the fixture.
- Workflow inputs, run names, bake order and release notes are public too. Bake whole countries or the whole catalog, never the maintainer's region by itself.
- An assistant that knows where the user is must not write it into code, docs, commits or its own notes. Use it while reproducing a bug; write up the mechanism only.
- Screenshots use Settings > Diagnostics > Simulate my location and Simulate driving. Check the corners: recents, labels and street names.
- Recorded trips, diagnostics exports and adb dumps hold raw GPS. Never attach them to an
issue or a commit. The in-app Share on a trip trims the ends (
core/replay/TripScrub). - When reading someone's recorded trip, print road names as tags (R1, R2) and never a name or
a coordinate. A tool's output is a transcript too. The study harness prints instructions both
after a
|and inside quotes; mask both. - A log line never carries a coordinate, typed text or a place name. A page probe logs
location.pathname.split('/@')[0]: Google puts the session's location after/@. scripts/check-location.shruns in the pre-push hook against a private list at~/.vela-location-termsand fails the push when a term matches. It never says which. CI runs the same test from theLOCATION_TERMSsecret. After editing the list:gh secret set LOCATION_TERMS < ~/.vela-location-terms.
What Vela never does¶
- No Google Play services, Firebase, Fused location, Play Integrity or any Google SDK.
- No static Google API key. Requests are made the way a logged-out browser makes them.
- No Vela backend, account or telemetry.
- No proprietary assets in the repo (fonts, map data, voices).
Build¶
./gradlew :app:assembleRelease # what goes on a phone
./gradlew :app:compileDebugKotlin # compile check
./gradlew :core:test :app:testDebugUnitTest
- Run release builds on a device. A debug build drops frames (14.8% janky against 1.1% on a Pixel 4a for the same gestures) and reads as a performance bug.
- Never uninstall Vela from a test phone: it deletes saved places, trips and permission
grants. Install over it with
adb install -r, with-PappVersionCode=set to the installed build's code. A side-by-side test build is-PappId=app.vela.dev. - A fresh clone needs the vendored binaries first (OsmAnd router jars, the Cronet AAR, the
sherpa-onnx AAR).
docs/BUILDING.mdlists them. - Toolchain versions are in
gradle/libs.versions.tomlandgradle.properties. compileSdk 37, targetSdk 35, minSdk 26, Java 17. AGP 9 builds Kotlin in: there is noorg.jetbrains.kotlin.androidplugin and nokotlinOptions. - Do not take core-ktx 1.19, navigation-compose 2.10 or hilt-navigation-compose 1.4 in passing. They pull Compose from 1.7 to 1.10 across the app, which is its own job.
- The Gradle actions (setup and wrapper validation) stay on v5. From v6 their caching is closed
source under Gradle's terms. Every action in every workflow is pinned to a commit SHA, and a
new workflow declares
permissions:. - Library versions held for the build tools' sake (lint, the plugin classpath, the baseline
profile module) are at the top and bottom of the root
build.gradle.kts.
MapScreen is at two size limits¶
MapScreen is at the JVM's 64 KB method limit and at ART's verifier limit. The debug compile
catches the first ("Method too large"). Nothing at build time catches the second: the release
build compiles, then dies at launch on Android 14 with VerifyError, and on Android 16 the
screen silently stops recomposing.
- Add no new call or parameter to
MapScreen. Put new pieces in a child composable or a holder object (RouteActions,SavedActions,ShapeActions,MapFloaters,NavCorner). - After any edit to it, build debug and release, install the release build, and read logcat
for
VerifyError.
Releases¶
canaryis the working branch. Pushing it replaces the one rollingcanaryrelease. The release's tag is also namedcanary, so the bare name is ambiguous to git: push withgit push origin HEAD:refs/heads/canary, and name the local branch something else.mainbuilds and tests on push. A daily job (10:30 UTC) cuts a nightly prereleasev0.5.<run>when main has moved. Mondays 16:00 UTC the newest nightly is promoted to stable. Do not dispatch CI per merge.- Releases are cut inside
ci.ymlbecause the version code is(2000 + run number) * 10plus a chip digit. Another workflow would restart the count. - Commit subjects are the changelog users read in the app. Write them as plain sentences
about what changed for the user. Start a docs-only commit with
Docs:; it is left out, as are changes that only touch docs paths. - A stable's notes lead with a short hand-written "What's new" list. The in-app dialog shows the release body as it is.
release.yml("Release now") takes main's head to a nightly or a stable in one manual run and is the only by-hand path: it cuts throughci.ymland promotes the build it cut, with the What's new list as an input. It is the maintainer's to start, or to approve each time.- Never name a release
v0.5.0by hand. The updater reads the run number out of the tag. - Contributor pull requests are read in full and tested before they land, and are taken by cherry-pick with the author kept.
- A pull request is presented for review in this order: what it does, what was tested and on what, what was not tested, the edge cases and known gaps, then the verdict and where the risk sits. The diff is re-read before presenting.
- Ready means every check the rigs here can run has been run: the phone, the Desktop Head Unit, the mock location provider, the simulated drive, the unit tests. What is left on the not-tested list is what needs a real car, another country or another person. An untested item that could change the verdict makes the verdict not ready, and the review says what would make it ready. A verdict that moves when the list is questioned was wrong when it was written.
The other releases are the download backend¶
Every tag that does not start with v0. is file hosting: voices, speech models, the Cronet
and sherpa builds, routing regions, place packs, the places and basemap archives, overlays,
map fonts, road features, cameras, grid cells, UK fuel prices. Those files exist nowhere else.
- Anything that deletes or edits releases selects by the tag pattern
v0.*. Never by "prerelease" or age. A cleanup that did otherwise took four offline features down. - The repository has hundreds of releases. Page through
gh release list, or bound it by tag. - A workflow lists the app's releases with
scripts/app-releases.sh. The REST release listing returns every asset of every release: a page of 100 is 25 MB and takes 9 s, and a promotion failed on HTTP 504. - A release that is one of many (the
cells-<region>set) is created on the root commit. GitHub sorts by the target commit's date and Obtainium reads the first hundred. - The Actions token has 1,000 API requests an hour for the whole repository. GitHub calls in
a workflow go through
scripts/gh-retry.sh, and a bake leaves 200 for everything else. - Bakes have no schedules of their own.
bake-conductor.ymlstarts one at a time fromtools/bake-schedule.json. A new bake is an entry there. The exception isfuel-gb.yml(UK fuel prices), which checks hourly on its own cron: it fetches one small file and spends no API request while its source is unchanged. - Every OSM extract download goes through
scripts/fetch-pbf.sh. - A manifest is derived from the files on its release (
scripts/repair-*-manifest.sh), never from one run's own output. A pending job in a concurrency group is canceled when a newer run joins, after its files are already uploaded. - Under
set -o pipefail,gh api --paginate ... | head -1dies with exit 141. Usesed -n 1p. - A job that fails for a reason no retry can fix (an upstream source with no data, a build a
newer push has overtaken) ends green with a
::warning::. A red run is mailed, retried by the conductor and shown as failing on the dashboard, so it is kept for things someone must fix.
GitHub Pages is one artifact¶
fdroid-repo.yml deploys the landing page (site/), the F-Droid repository (/repo), the map
fonts (/fonts) and the docs site (/docs) together. A second Pages workflow would replace
all of it. Never rerun only a failed deploy job; start a fresh run.
The same workflow also publishes the landing page, the press page, the privacy page (built
from PRIVACY.md by scripts/build-site-privacy.py, so edit the Markdown, never an HTML
copy) and the press kit to
velamaps.org (Cloudflare Pages, project velamaps). That is the website only. /repo, /fonts
and /docs live at the GitHub Pages address and must stay there: installed apps fetch their map
fonts from it and every F-Droid client points at it. Do not set a custom domain on the GitHub
Pages site, which would turn that address into a redirect.
Keys¶
- App signing:
~/.vela-signing/vela-release.jks, repo secretsVELA_KEYSTORE_*. The certificate's SHA-256 is published in the README. - F-Droid index:
~/.vela-signing/fdroid.p12. - Remote settings:
~/.vela-signing/vela-calibration.key. The public half is pinned inCalibrationStore.PINNED_PUBLIC_KEY.
None of these is ever committed.
Remote settings (calibration.json)¶
The request templates, response paths, word tables, fleet defaults and tuning dials are in a signed file the app fetches at launch (SPEC 11).
- To ship a fix without a release: edit
calibration.json, raiseversion, run./scripts/sign-calibration.sh, commit the file and its.sigto main. Calibration.DEFAULT.versionstays 1 so that any published file wins.- A new field in
Calibrationalso needs reading inCalibrationStore.parseBundle. Grep for the field name there. Fields have been added and never parsed. - A new Google request goes into calibration the day it ships.
- Every link to the project itself (repository, releases, site, this file) comes from
VelaLinks(SPEC 11.4), never a literal, so a moved repository or a renamed account is a signedlinkspush and a defaults edit, not a hunt through the code. - The website carries a copy of the file and its signature (
fdroid-repo.ymlpublishes them with the site), and the app reads that copy when GitHub does not answer. Keep both files in the same commit; the site deploys on a push to either. - Before pushing a change, run the health probe against it:
./gradlew :core:testDebugUnitTest --tests '*GoogleHealthProbeTest' -DvelaLive=true. - Read the live file before saying a dial is off. Compiled defaults and fleet values differ.
- A dial that opens the app up for inspection (WebView inspector, network log, reply dumps)
reads
AppTune.localOn, which only adb can set.
Layout¶
:corehas no UI. It holds everything that talks to Google and the open services, routing, navigation, parsing, and the offline stores.:appis the Compose interface. MapLibre and Android UI types stay out of:core.core/data/MapDataSourceis the one seam.GoogleMapsDataSourceimplements it.:appcannot be read from:core. A setting that must act inside:coreis mirrored into a flag there (NoGoogle,LowRamMode,LowDataMode,CategoryFilter,RoutingPrefs,RoadNumbers).- Settings are process-wide holders (
ui/AppTheme,ui/Units,ui/PlaceContent.ktand the like), started inVelaApp. A holder that is not started there reads its default on every launch. MapViewModelis large. Navigation lives inNavController, reached throughNavController.Host.- A hidden Google page is a subclass of
web/HiddenWebView. Never copy the WebView plumbing. NavSessioncounts stops only while the engine's route (_state.route) is the very object inplanRoute. Replace both together or neither.MapViewModelandNavControllerproperties that aninitcollector touches are declared aboveinit.viewModelScopeisMain.immediate, so a collector's first pass runs inline, before anything declared below exists.
Traps¶
Kotlin and Android¶
- In a Kotlin raw string,
${'$'}{x}is not a template. It emits the literal text. - A
$namefollowed by a CJK character parses as one identifier. Write${name}. - In
strings.xmla raw apostrophe fails the release resource merge, and a raw double quote is silently removed. Escape both. A warm Gradle daemon hides this; CI does not. - Match a placeholder's type to its argument.
%dgiven a String crashes. - Android's regex is ICU.
\p{IsHan}and an unbalanced}throw on a phone and pass every JVM test. UseCharacter.UnicodeScriptor\p{Han}, andRegex.escapefor literal text. - A
Regexthat throws in anobjectinitializer takes the whole object down for the life of the process. Never build aRegexinside a per-item loop either. - A literal
*/inside a KDoc comment (a wildcard mime type,del_*/ins_*) ends the comment. android.location.LocationListeneris implemented as an explicit object with all four callbacks. The lambda form crashes on Android 10 and below.Locale("zh-TW")makes a bogus language. UseLocale.forLanguageTag.- Read the device locale from
Resources.getSystem().Locale.getDefault()is the in-app language onceAppLocale.wraphas run. - The 12 or 24 hour clock is a device setting, not the locale. Use
Clock24/ClockFormat. InputStream.readNBytesis API 33. minSdk is 26.- An early
return@forEachIndexedinside a composable lambda can crash the Compose compiler. withTimeoutOrNullonly interrupts at a suspension point. A blocking socket read or the offline router's native compute outlives it. Run those on an unstructured scope so the deadline can abandon them, and never gate later work on that job's liveness alone.- In app unit tests
org.jsonis a stub andandroid.util.Logthrows unlessisReturnDefaultValuesis set. - aapt un-gzips and renames an asset ending in
.gz. Use a neutral extension. PolylineCodechandles 5, 6 and 7 decimals. Keep its accumulators 64-bit.- A "changed since last frame" test against a value that starts as NaN is never true. Test
isNaN()first. File.renameTofails across volumes, and the cache folder is always internal. Stage a download beside its target, and move the old copy aside before the swap, never delete it.- A point at a distance along a line is
RouteProjection.pointAt(a binary search). A scan from the start inside a loop over the same line is quadratic on a long route.
Network¶
- The shared OkHttp client has a 12 second call timeout. A download through it stops
mid-body, the error is swallowed, and the file silently never installs. Every large
download uses a client with
callTimeout(0). - On a Google host
callTimeout(0)is not unlimited: the Cronet transport bounds it at 30 s. A Google reply of megabytes takes a client with a set deadline (GoogleMapsDataSource.largeReplyHttp). - Parse a large response from the stream into a small DTO. Reading the body to a string and building a JSON tree holds five to ten times the wire size.
- Every request that can reach Google goes through the shared client, which counts it and hands it to Cronet. A separate client breaks the count and the browser identity.
- Google requests send the calibrated browser identity (
calibration.current().userAgent,BrowserHeaders). OSRM, Valhalla, Nominatim, Photon, Overpass and Transitous getVelaConfig.VELA_UA, the honest one. Never mix them. - Never add a Google request value every install sends identically. Derive counters, callback
names, spans and viewports per session (
RequestShape,BrowserViewport). - Timed Google requests are spread with
core/util/Jitter. - Never probe Google's review feed from the maintainer's own connection.
- Any new Overpass query goes through
OverpassEndpoints.run. Nominatim's maintainer asked Vela off public Overpass for bulk work; baked files are the first source. - A long download runs through
MapViewModel.downloadLaunch, which outlives the screen and holds a foreground service, and it shows a Cancel wherever it shows progress. - An empty answer from the nearby-places fan-out is a failure, not a result. Never cache it.
WebViews¶
- Every WebView calls
WebViewIdentity.apply. Never setuserAgentStringby hand. - A script that calls a bridge goes through
JsNames.of, which swaps in the per-process names. - A new WebView-built fetcher calls
SessionRotation.consumeCacheClear. - Google's tab and button labels embed the place name. Strip it (
STRIP_PLACE_NAME_JS) before testing a label for a word. - A hidden WebView is 0 by 0 unless given an offscreen viewport, sized in CSS pixels times density.
- Pause a hidden WebView when its fetch is done. A loaded Google page keeps a compositor and timers running.
- A Compose dialog cannot be made to cover the system bars. A full-screen viewer leaves the bars visible and draws a gradient under the status bar.
The map (MapLibre)¶
maxzoomon a layer is exclusive.getMetersPerPixelAtLatitudeis meters per dp, not per physical pixel. The scale bar sized itself in pixels and its label was too large by the screen's density.- Past a GeoJSON source's
maxzoom, every visible tile lays out all of its parent's features. A dense source gets maxzoom 16 to 18. - An 8-digit hex color string is rejected and falls back to opaque black. A layer at opacity
0 is skipped at render and returns nothing to
queryRenderedFeatures. An invisible but queryable layer is black at opacity 0.004. - An unstyled
LineLayerdraws black. A new twin layer is colored in every palette function. - A
fill-patternfrom the style cannot be cleared. Hide the layer and add a flat twin. - An image added under a name the sprite also has loses to the sprite. Use
vela-names. - Draw order and collision order are the same thing: the topmost symbol layer places first. A layer that must not evict icons goes below them.
- A filter change or a data-driven paint change re-runs placement for the whole layer. Do not key either on drive progress.
- The style's own source id changes when a downloaded basemap is mounted. Reach the basemap
source through
basemapSrc(style). - Liberty's layers that the palette functions do not name keep their light colors in dark mode. Name new ones.
querySourceFeaturesandqueryRenderedFeaturesblock on the render thread. Gate them by time and distance, never per frame or per idle event.- Camera-idle fires after every
moveCamera, 60 times a second while a ticker follows. - A SurfaceView's window hole does not follow a Compose resize. Recreate the view.
- An interceptor on MapLibre's HTTP client is installed after
MapLibre.getInstance. - The pmtiles path never cold-fetches a tile two or more levels under the camera. A layer whose archive stops at z17 arms at z17 and gates visibility by opacity.
- A streamed
pmtiles://https://source goes throughStreamedPmtiles(overlaySource), never straight to MapLibre: since MapLibre 13 its PMTiles cache answers one range with another's bytes and the source fails withincorrect header check. Apmtiles://file://source loads. - The bundled style JSON is one minified line. Edit it with a script that re-dumps compact.
- Never keep a
Layerobject fromstyle.layerspast the call that fetched it. Keep the id and the style, and look the layer up again on that same style: after a reload the old objects point into a style that is gone. setAllGesturesEnabled(true)turns every gesture on, tilt and rotation included. Apply a gesture setting after it.- Three things move the camera to the fix in the first second of a launch: the first run of the
recenter branch, the first target fly, and the launch-center effect. A map that opens anywhere
else starts with all three marked done (
startFramedinVelaMapView).
Frame rate¶
- Measure before changing physics. Record the screen and take a Perfetto trace. A hitch at the GPS fix rate is main-thread work.
dumpsys gfxinfocannot see the map, which draws on its own GL thread. Usedebug.vela.fps(read at map creation) andscripts/map-fps.sh.debug.vela.hide "<prefix or type:symbol>"hides layers for bisecting.- Check thread CPU first:
adb shell top -H -b -n 2 -d 5 -p <pid> -o TID,%CPU,CMD. MapLibre's native threads inherit the name of the Java thread that started them. - Test in a dense city at replay speed, with cool-downs. The 4a throttles after a few minutes and every number drops.
- A layer A/B (
debug.vela.hide) alternates its arms in a balanced order and has a placebo arm with some other layer hidden. The first sweep into a zoom level pays for cold tiles, so the arm that always goes first looks worse. Compare total frames over identical gestures. - A
withFrameNanosloop needs an idle exit, and every write in it is change-gated. A parked drive must draw nothing. - Anything that must sit still on screen while the map moves is a Compose overlay projected from the camera, not a GeoJSON symbol updated per frame.
- Route geometry is never moved per frame. The moving cut is a paint change on a short piece.
- An
alphabelow 1 on agraphicsLayerrenders offscreen. UseCompositingStrategy.ModulateAlpha. - Read fast-moving values in the layout or draw phase. Give composition threshold booleans.
- No blocking IPC or file IO in a composable body. Use
produceStateonDispatchers.IO. - A new large or native allocation registers a releaser with
MemoryPressure. - Do not unbound the nearby-places fan-out (four parses at a time). Unbounded, it filled the heap and stalled every allocation.
Compose¶
- A Compose
DropdownMenuorAlertDialogcannot be given focus. UseVelaMenuandVelaDialog. - Every screen opens with something focused (
rememberDpadAutoFocus), every control has a focus ring (dpadHighlight), and every gesture has a key path. D-pad code calls the touch paths.docs/dpad.mdhas the rest. CI runsdpad_test_suite/audit_static.sh. - D-pad detection counts a touchless device or a physical D-pad only. The virtual input device reports a D-pad on every phone.
adb shell input textflips the app into keyboard mode. Type test input by tapping keys.- A
LaunchedEffectkeyed on a tick fires on first composition too. A sheet that takes a tick remembers the value it mounted with. - A drag list keeps one modifier chain and varies the values. Changing the chain when the drag starts kills the gesture.
- An
IconButtonis 48 dp at least, whateverModifier.sizesays. - A
pointerInput(Unit)block keeps the callback it started with. Read one that can change throughrememberUpdatedState, or a dialog that asks a second question runs the first answer. - Read light or dark with
isAppInDarkTheme(), and for things drawn on the mapisMapDark(). NeverisSystemInDarkTheme(). - Read wallpaper colors with
wallpaperColorsInUse(), not the switch. - Chrome and transient surfaces take
MaterialTheme.colorScheme. Content inside a place or results sheet takesSheetPalette. On a colored container use that container's own on-color. - Every chip is a stadium pill (
CircleShape). A confirm button is a filled pill. - A sheet is a hand-driven
Animatableread in the layout phase (sheetDragGestures,SheetFold). Do not add another gesture system. - New content above the place sheet's action row reserves its space from the first frame.
LocalConfigurationis provided byMainActivity, which handles rotation itself.- Icons are
SymandSymOutlined, generated byscripts/gen-symbols.py --rewrite. - New map chrome goes inside the
!pipUigate and gets the landscape column treatment (landscapeColumn). - Drive chrome that can cover the arrow's column reports its edge to
NavChromeEdges, or the camera frames the arrow and the road ahead under it (SPEC 4.7, Framing).
Android Auto¶
- Every
Maneuversent to the car has an icon. The host draws no turn card for one without. - When a new car
Surfacearrives, release the old one. It holds the buffer queue's connection. - A row image that has colors is
Row.IMAGE_TYPE_SMALL. The host tintsIMAGE_TYPE_ICON. - Only
VelaCarSessionpushes the drive screen. updateTrip()goes out at most once a second. The host drops faster ones.MapSnapshot.pixelForLatLnganswers for a point behind a tilted camera with its mirror image. Anything drawn on the car map goes throughprojectorpathOf, which leave such points out.
Data and bakes¶
- A rule in
tools/build-places-region.shthat relates rows to rows needs an equality to hash on. An OR of tests or a correlated subquery does not finish on a state. - The script's DuckDB block is an unquoted heredoc. A backtick in a SQL comment runs as a shell command.
- Never edit a bake script while a bake is running. Bash reads it as it goes.
- Prune a cloud parquet read on its
bboxcolumn. A test on computed coordinates reads the world. - DuckDB, tippecanoe, go-pmtiles and planetiler are pinned. Move a pin only after a local bake.
- A new rule names the old Overture category.
tools/overture-taxonomy-map.csvmaps the new names back. PlaceNamesis the one same-business rule, shared by the app and the bake.tools/place-generic-words.txtis generated from it; a test keeps them equal.- Check a bake wave by counting file dates on the release, not by the run's color.
- A region is chosen by its real boundary (
RegionPolys), not its bounding box. After adding a catalog row runscripts/region-polys.py. - A catalog
pbf_urlcan becut:<parent id>:<polygon file>, a region cut from another row's extract (SPEC 7.2). Onlyscripts/fetch-pbf.shreads it. Never download or take apart apbf_urlanywhere else. - A US state offered in parts goes in
US_SPLIT_STATES(OfflineSettings.kt). Without it the parts list as a parent of their own beside the countries, and the old whole-state row stays beside them. - A new part is listed in the app as soon as the routing manifest has it. Bake its place pack, places, basemap, road features and cells first, or its download pulls the parent's archives.
- A store of downloaded data takes its folder from
StorageLocation.rooton each access and adds it toStorageLocation.FOLDERS. - A new preference file or user data file is not backed up until it is in both
res/xml/backup_rules.xmlanddata_extraction_rules.xml. - A change to a stored format reads the old key once and writes a new key. An older build then still finds its own data.
- A list or saved place is matched with
ListPlace.matches(id or Google feature id), never by id alone. - A new line kind in
TripLogneeds a decision inTripScrubon whether it is safe to share.
Languages¶
- English strings go in
values/strings.xml. Translations come from Weblate, whose pull requests merge themselves after a check. After one merges, mergeorigin/maininto the working branch before the next push. - A string for a feature still behind a switch is not
translatable="false". That flag is for the app name and the map credits. - A count that can be 1 is a
<plurals>with the right categories per language. - Names, addresses and reviews are data and are never translated.
- Text that decides something (open or closed, transit categories, review page labels) is matched against per-language word tables that calibration can replace. When a language misbehaves, capture the real text before guessing a word.
- The open or closed state is parsed from the status text. The numeric codes beside it are styling.
- Accents are folded off Latin letters only (
OfflineRank.fold). Decomposing every script and dropping the marks takes the voicing marks off kana, splits Hangul and drops Thai, Devanagari and Arabic vowel signs, and text folded that way no longer matches a stored name.
Testing on a phone¶
- Fake the location with Settings > Diagnostics > Simulate my location. Tap the switch, not the row. Put it back on Davis afterward.
- A drive with no GPS: Simulate driving. Turn both off for real use.
- A moving test without the simulator: add
gpsandnetworktest providers before turning location on, feed fixes once a second, and turn location off before removing them. - Another app language:
adb shell cmd locale set-app-locales app.vela --user 0 --locales ja. - Large fonts:
adb shell settings put system font_scale 1.3. - A fixed time of day for transit and opening hours:
setprop debug.vela.tune.demoClock 720(minutes after midnight). Clear it afterward. - Any tuning dial:
setprop debug.vela.tune.<key> <n>. - A route without the map matcher (tile names, the nudged line):
setprop debug.vela.tune.noMatch 1, then restart the app.VelaDirectionslogs how each stretch was named and the meters nudged. - Low-memory path:
setprop debug.vela.lowram true. - A trip between two points without moving the simulated location: open
https://www.google.com/maps/dir/?api=1&origin=..&destination=..as a view intent. Pass the wholeam startcommand toadb shellas one quoted string, or the shell cuts the link at&, drops-p app.vela, and another maps app opens it. - A simulated drive's fixes skip the live fix handler (
replaying). Anything that should run per fix in a demo is also called fromNavController's replay collector, throughHost. - Two-finger gestures cannot be injected with
input: usescripts/touch/two-finger.sh. Its[repeat] [cycles]arguments play a zoom sweep out and back in one process. A held back swipe can, withinput motionevent.setprop debug.vela.fps truelogs the camera zoom once a second (VelaFps), which is how to tell whether a pinch zoomed. - Log tags worth knowing:
VelaDirections,VelaSteps,VelaCaptureandVelaSpeak(set to DEBUG;VelaSpeakprints every spoken line, names included, so only on a test phone),VelaTap,VelaSearch,VelaTransit,VelaDelta,VelaUpdate,VelaWeb,VelaSession,VelaFps,VelaCar,VelaSim,VelaPassAlert. - The Android Auto desktop head unit shows Vela's car screens but skips the car's install check. Book chapter 10 has the setup.
- Restore whatever a test changed on the phone.
Checks to run before trusting a routing change: core/nav/StepAudit, then
NamingStudyTest.replayCapturedLines (-DvelaStudy=1), then a few real trips on a phone with
the step list read by hand. A change to naming from the tiles (LineNamer, RoadNameTiles)
also runs NamingStudyTest.tileStepCensus -DvelaCensus=<file> before and after and diffs the two
files: every step of the captured lines, both modes. -DvelaOne=<file name> adds each bend's
inputs. A line with a <name>.exits beside it also has Google's exits from its reply. Probe tests that need a region file take -DvelaObf=<folder>.
RoadCenterTest.deskLine (-DvelaNudge=<file>) nudges a captured line and writes it out for
drawing.
Reading a shared trip (SPEC.md 4.10 has the line kinds): each route block's RD line says
what made the steps (source=, named=KofN, then Route.made), the K notes say what the
drive decided, and S lines are what the voice said (or, marked (muted), would have said).
N lines are what the nav engine was handed and RC lines every route a router answered, with
a route answers note per fetch; both hold positions, so read them through masked tools only.
To try a rerouting change on a recorded wrong turn, replay the trip on a phone with
adb shell setprop debug.vela.tune.replayLive 1 (re-drive, SPEC 4.10).
To see how a route in it would be named now, save its RP line as the only .txt in a folder
and run
NamingStudyTest.replayCapturedLines -DvelaStudy=1 -DvelaOne=1 -DvelaLines=<folder>.
Where things are written down¶
| File | Holds |
|---|---|
README.md |
What Vela is, what reaches Google, install |
FEATURES.md |
What the app does, one line each |
SPEC.md |
The technical reference |
docs/book/ |
Each subsystem explained |
ROADMAP.md, docs/ROADMAP-HISTORY.md |
What is open; what shipped or was dropped, and why |
PRIVACY.md |
What each service receives |
docs/FAQ.md |
The first questions people ask |
docs/BUILDING.md |
Building from source |
docs/TRANSLATING.md |
Languages and how to translate |
docs/dpad.md |
Operation without a touchscreen |
docs/ANDROID-AUTO.md |
Android Auto for users |
CONTRIBUTING.md, SECURITY.md, FDROID.md |
As named |