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

Proposed by Bret Barker on 2016-01-04
Status: Merged
Approved by: Bret Barker on 2016-01-04
Approved revision: 199
Merged at revision: 198
Proposed branch: lp:~noise/tanuki-agent/tutorial-first-boot-edits
Merge into: lp:tanuki-agent
Diff against target: 71 lines (+45/-7)
1 file modified
docs/tutorial-products.md (+45/-7)
To merge this branch: bzr merge lp:~noise/tanuki-agent/tutorial-first-boot-edits
Reviewer Review Type Date Requested Status
Facundo Batista 2016-01-04 Approve on 2016-01-04
Review via email: mp+281531@code.launchpad.net

Commit message

review/edit of the new first-boot tutorial section

To post a comment you must log in.
Facundo Batista (facundo) wrote :

Wonderful work

review: Approve
199. By Bret Barker on 2016-01-04

spaces and typo

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'docs/tutorial-products.md'
2--- docs/tutorial-products.md 2015-12-22 20:06:06 +0000
3+++ docs/tutorial-products.md 2016-01-04 16:26:41 +0000
4@@ -623,22 +623,60 @@
5
6 ## First-boot tests
7
8-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.
9-
10-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).
11-
12-This way you can list all the Product Base Images for a given product.
13+When you promote packages to a ```base_channel``` that you have
14+specified in a Test Spec, the system creates what is called a Product
15+Base Image. This is a point-in-time snapshot of the revisions of all
16+of a Product's snaps from the given ```base_channel```. This set of
17+snap revisions is used to generate the initial image to provision a
18+device prior to applying snap updates for testing.
19+
20+From a product lifecycle perspective, the latest Base Image
21+represents what is currently in the field on customer devices that
22+have been receiving regular updates. However, there is another
23+scenario to consider - the "first boot" update that happens when a
24+customer connects a new device to the internet for the first
25+time. This device will have an older image that was flashed onto it during
26+the factory install.
27+
28+As an example, let's say that have been doing GM testing and finally
29+have an image ready to release that includes revision 5 of your
30+snap. Some customers start using your shipped devices and over time
31+update to revision 6, then 7, and then 8. Each of those just 1
32+revision at a time. Then a new customer installs a device that is
33+still at the factory revision 5 of your snap and when connected will
34+receive an update from revision 5 to 8. This is the "first boot"
35+scenario and we'll now explain how the Product Integration System
36+accomodates that.
37+
38+First, you can query the system to list all Product Base Images for
39+your Product:
40
41 ./api_example.py -X GET config.ini https://spi.canonical.com/products/$PRODUCT_ID/baseimages
42
43-To mark any of those as released, just do:
44+When you have a Gold Master that you release to manufacturing (or
45+perhaps as a built image for download), you can mark that Base Image
46+as "released" via the API:
47
48 ./api_example.py -X PUT config.ini https://spi.canonical.com/products/$PRODUCT_ID/baseimages/<baseimage_id> --data '{
49 "released": true
50 }'
51
52-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:
53+Now, when you publish new snap revisions to a Test Spec's
54+```update_channel```, the system will create update tests for both the
55+latest Base Image as well as _all_ prior Base Images that are marked
56+as released (and not deactivated). This will ensure those extended
57+revision deltas are adequately tested before promotion.
58+
59+If for whatever reason you no longer want update tests to be performed
60+for an older releaded image, you can deactivate it by doing:
61
62 ./api_example.py -X PUT config.ini https://spi.canonical.com/products/$PRODUCT_ID/baseimages/<baseimage_id> --data '{
63 "active": false
64 }'
65+
66+That's it! You now have automated testing setup for three different
67+scenarios across the Product lifecycle. For further details you can
68+consult the reference documentation:
69+
70+ - [Agent Reference](agent-reference-products.html)
71+ - [API Reference](api-reference-products.html)

Subscribers

People subscribed via source and target branches

to all changes: