diff options
Diffstat (limited to 'toolkit/mozapps/update/updater/macos-frameworks/UpdateSettings/README.md')
| -rw-r--r-- | toolkit/mozapps/update/updater/macos-frameworks/UpdateSettings/README.md | 77 |
1 files changed, 77 insertions, 0 deletions
diff --git a/toolkit/mozapps/update/updater/macos-frameworks/UpdateSettings/README.md b/toolkit/mozapps/update/updater/macos-frameworks/UpdateSettings/README.md new file mode 100644 index 0000000000..32b9d2ea48 --- /dev/null +++ b/toolkit/mozapps/update/updater/macos-frameworks/UpdateSettings/README.md @@ -0,0 +1,77 @@ +# UpdateSettings macOS Framework + +## Summary + +The UpdateSettings macOS Framework is used to set the accepted MAR download +channels. + +## What are MAR update channels and what are they used for? + +As the name implies, MAR update channels are the channels where MAR update files +are served from and we want to ensure that the updater only applies MAR files +from accepted channels. + +## Why do we need a Framework instead of compiling the accepted MAR update channels directly into the executable? + +There are three main use cases that make it necessary for the accepted MAR +update channels to be set by external means, such as a macOS Framework: + + 1. Allowing users on the Beta channel to test RC builds + +Our beta users test release candidate builds before they are released to the +release population. The MAR files related to release candidates have their MAR +channel set to `release`. We make it possible for beta users to test these +release candidate MAR files by having beta Firefox installs accept MAR files +with their internal update channel set to either `release` or `beta`. + + 2. Switching users to another channel, such as ESR + +In contrast to the Beta use case outlined above, there are times where we +explicitly WANT to switch users to a different channel. An example of this is +when hardware or a particular macOS version have reached their EOL. In this +case, we usually switch users to our ESR channel for extended support. We switch +users to a different channel by serving a MAR file that forces a change to the +update channels that will be accepted for future updates. In other words, while +users may have previously accepted MAR update files from the `release` channel, +they now only accept MAR files from the `esr` channel. + + 3. QA update testing + +QA requires a way to temporarily switch the MAR update channel to a test channel +in order to test MAR updates before new releases. + +## How does the UpdateSettings macOS Framework address these use cases? + +We are able to accommodate all three use cases above by enabling the updater to +ignore certain files on disk if they are already present, but continue to force +update them if so desired. + +In the case of a Beta user updating to an RC build, the updater would encounter +an UpdateSettings macOS Framework inside the .app bundle that has the accepted +MAR update channels set to `beta` and `release`. In this case, the updater will +not update the Framework, but update everything else. This beta user is now able +to run the RC build with the update channel still set to `beta` and `release` +and will be able to apply MAR files related to the next beta cycle once the end +of RC builds is reached. + +In the case of switching users to the ESR channel, the updater will be set to +forcefully update the UpdateSettings macOS Framework, even if already present on +disk. After the update, the user will now be set to accept MAR updates from the +`esr` channel only. + +Before releases, QA replaces the UpdateSettings macOS Framework within the .app +bundle and set the accepted MAR update channels to a test channel in order to +test MAR updates. During testing, the new Framework file would remain in place +for typical update testing, but gets replaced in case QA was testing channel +switching. + +## Why is a macOS Framework the best solution to store the accepted MAR update channels? + +Apple has started strengthening code signature checks and the requirements on +developers such as ourselves on how their apps are signed. In particular, +most files in the .app bundle are now included in signature verifications. + +A macOS Framework is the ideal solution to store the accepted MAR update +channels because Frameworks are the only component within a .app bundle that can +be replaced without invalidating the code signature on the .app bundle, as long +as both the previous and the new Framework are signed. |