View source for Gaia/System/Updates/Gonk

== Overview ==

Changes to this layer in the software stack should only be made when it is absolutely necessary.  The requirement here is to ensure a stable build at this level of the software to minimize any issues with the phone at the Gaia level. 

* Gonk updates are synonymous with Full-System and FOTA.
* FOTA = Firmware Over-the-Air
* Full System = atomically update Gonk+Gecko+Gaia.
* Require rebooting device (because Gonk requires reboot).
* Update takes several minutes, during which device is unusable.
* Will only used for security bugs in Gonk that cannot be fixed in Gecko or Gaia.
* Ideally are never needed for shipping devices.
* Frequency:
** Immediate for critical security bugs.
** Quarterly for any non-critical security bugs, if needed. If there are no bug fixes in a given quarter, there is no quarterly update.
* User can view currently version information from Settings > Device > Device Information.

== UX Requirements ==

==== WIP notes, Josh Carpenter, Aug 15 ====

* Need to find right balance of automatic versus user-approved.
* Prompt user when update is available? 
* Prompt user to approve download? eg: "download now" [or] "download later" (placeholder verbiage). Or initiate automatically when certain condition is met (eg: connected to WiFi, and device is inactive).
* After download complete, prompt user to install? eg: "Install now" [or] "Install later" (placeholder verbiage).
* Display download progress to user (progress bar)?
* Display install progress to user (progress bar)?
* Minimize the risk of unsuccessful install, the consequences of which can include bricking the device.
** Detect battery life and require user first connect to power source if below X%?
** Detect low-available device storage and prompt user to clear files before they can proceed?
** Detect interrupted download (eg: user turns on Airplane mode, user powers down device, etc) and seamlessly complete (or restart) later?

== Questions ==

=== Open ===

* Risks: what causes botched installs?
** Battery dies in process?
** Insufficient storage?
** Corrupted update files?
* How do we mitigate those risks?
* Once update has downloaded and user has opted to install, what is the install sequence? eg: Shut down to blank screen, show progress indicator, 
* Backup: is there a rollback feature for failed installs? (Sounds like answer is no).
* File size: Approximately how large are these updates? Do we check for available device storage before downloading? If insufficient, how do we mitigate?
* If user defers installation of update:
** ...presumably they cannot receive subsequent Gecko + Gaia updates?
** ...do we remind user to reinstall later on? 
** ...and/or automatically install at future point (eg: next time the device reboots)
* Can we confirm that Full-System updates will be free via Carrier's private APN?

=== Answered ===

* What is time to install? Several minutes?
** (cjones from IRC): Several minutes, during which device is unusable.
* Do we require the user to plug in the phone if battery is below X %?
** (sicking) This is somewhat technically doable, but a UX decision if we actually want to. What we can't do is estimate how good the battery is. I think an old "worn out" battery will fall much quicker in battery level than a new one. It's also hard to get a good estimate of how much battery is needed, but we can certainly require battery levels much higher than what's needed (say 30%).
* Can we avoid user friction by downloading silently, and only during periods of user inactivity? Would not want to slow down web browsing while update processed in background, for example.
** (sicking) We don't have good mechanisms for giving lower priority or throttling individual channels in Necko right now. We technically could detect other downloads starting through and abort the update in that case, and then resume once we detect user inactivity.
* Do we provide link to changelog so user can review update details before installing?
** (sicking) I think this is up to UX to set requirements. Seems technically feasible, but I'm not convinced it's needed given that in every instance we'll likely want to apply the update for security reasons.
* If the user powers down the device while an update is silently downloading in background, can we resume download later on?
** (sicking) Necko has the ability to download ranges, but this also needs server support. We certainly could require such support though.