Merge lp:~noise/tanuki-agent/tutorial-first-boot-edits into lp:tanuki-agent

[Bret Barker]

review/edit of the new first-boot tutorial section

[Facundo Batista (facundo)]

Wonderful work

review: Approve

[lp:~noise/tanuki-agent/tutorial-first-boot-edits]

199. By Bret Barker on 2016-01-04

spaces and typo

=== modified file 'docs/tutorial-products.md'
--- docs/tutorial-products.md	2015-12-22 20:06:06 +0000
+++ docs/tutorial-products.md	2016-01-04 16:26:41 +0000
@@ -623,22 +623,60 @@
 
 ## First-boot tests
 
-When you promote images, as said above, the system will generate new Gold Master candidate tests, creating Product Base Images that are the base for when testing Updates.
-
-Update tests will be created always using the latest Product Base Image, but if you release images you'll need the Update tests to also be created using those released images. This is handled automatically by the system, all you need is to mark the Product Base Image as released, and the Update tests will be generated using not only the latest Product Base Image, but also all those that were ever released (until you deactivate them).
-
-This way you can list all the Product Base Images for a given product.
+When you promote packages to a ```base_channel``` that you have
+specified in a Test Spec, the system creates what is called a Product
+Base Image. This is a point-in-time snapshot of the revisions of all
+of a Product's snaps from the given ```base_channel```. This set of
+snap revisions is used to generate the initial image to provision a
+device prior to applying snap updates for testing.
+
+From a product lifecycle perspective, the latest Base Image
+represents what is currently in the field on customer devices that
+have been receiving regular updates. However, there is another
+scenario to consider - the "first boot" update that happens when a
+customer connects a new device to the internet for the first
+time. This device will have an older image that was flashed onto it during
+the factory install.
+
+As an example, let's say that have been doing GM testing and finally
+have an image ready to release that includes revision 5 of your
+snap. Some customers start using your shipped devices and over time
+update to revision 6, then 7, and then 8. Each of those just 1
+revision at a time. Then a new customer installs a device that is
+still at the factory revision 5 of your snap and when connected will
+receive an update from revision 5 to 8. This is the "first boot"
+scenario and we'll now explain how the Product Integration System
+accomodates that.
+
+First, you can query the system to list all Product Base Images for
+your Product:
 
     ./api_example.py -X GET config.ini https://spi.canonical.com/products/$PRODUCT_ID/baseimages
 
-To mark any of those as released, just do:
+When you have a Gold Master that you release to manufacturing (or
+perhaps as a built image for download), you can mark that Base Image
+as "released" via the API:
 
     ./api_example.py -X PUT config.ini https://spi.canonical.com/products/$PRODUCT_ID/baseimages/<baseimage_id> --data '{
         "released": true
     }'
 
-After this step, that Product Base Image will be used in the Update tests. The moment you decide that any Product Base Image shouldn't be used for Update tests, you can deactivate it, by doing:
+Now, when you publish new snap revisions to a Test Spec's
+```update_channel```, the system will create update tests for both the
+latest Base Image as well as _all_ prior Base Images that are marked
+as released (and not deactivated). This will ensure those extended
+revision deltas are adequately tested before promotion.
+
+If for whatever reason you no longer want update tests to be performed
+for an older releaded image, you can deactivate it by doing:
 
     ./api_example.py -X PUT config.ini https://spi.canonical.com/products/$PRODUCT_ID/baseimages/<baseimage_id> --data '{
         "active": false
     }'
+
+That's it! You now have automated testing setup for three different
+scenarios across the Product lifecycle. For further details you can
+consult the reference documentation:
+
+ - [Agent Reference](agent-reference-products.html)
+ - [API Reference](api-reference-products.html)