Merge lp:~noise/tanuki-agent/misc-tweaks4 into lp:tanuki-agent

[Bret Barker]

lots of little wording and section name changes

[Celso Providelo (cprov)]

Thanks

review: Approve

=== modified file '.bzrignore'
--- .bzrignore	2015-10-08 21:35:21 +0000
+++ .bzrignore	2015-10-26 15:54:41 +0000
@@ -5,3 +5,4 @@
 __pycache__
 run
 version_info.py
+docs/*.html
 
=== modified file 'docs/tutorial.md'
--- docs/tutorial.md	2015-10-22 21:15:03 +0000
+++ docs/tutorial.md	2015-10-26 15:54:41 +0000
@@ -20,7 +20,7 @@
 
 In order to complete this tutorial, you will need the following resources:
 
--   A host computer running [Ubuntu 14.04](http://www.ubuntu.com/download/desktop), with an SD card reader.
+-   A host computer running [Ubuntu 14.04](http://www.ubuntu.com/download/desktop), with an SD card reader and at least 6 GB free drive space.
 -   A [Raspberry Pi 2 Model B](https://www.raspberrypi.org/products/raspberry-pi-2-model-b/).
 -   A minimum 4GB Micro SDHC card.
 -   The host computer and Raspberry Pi connected on the same local ethernet network.
@@ -30,7 +30,7 @@
 
 ## Introduction to Snappy Product Integration (SPI)
 
-SPI (Snappy Product Integration) is the system you will use to model your
+Snappy Product Integration (SPI) is the system you will use to model your
 product such that proposed updates will be automatically tested. Once
 configured, you will have the ability to prevent identified-broken updates from
 reaching your customers.
@@ -73,7 +73,7 @@
 
 IMPORTANT SECURITY NOTE:
 
-The config file now has data (```consumer_secret```, ```token_secret```, and ```token_key```) equivalent to your user and password. 
+The config file now has data (```consumer_secret```, ```token_secret```, and ```token_key```) that are equivalent to your password. 
 
 You are responsible for storing this securely. The device on which the
 Agent runs should be protected from unauthorized access.
@@ -103,7 +103,11 @@
 
     ./agent.py --register config.ini
 
-If you get a 401 error like:
+You should see something like:
+
+    [agent-queue] Registered at https://spi.canonical.com/orgs/my-org/labs/agent-groups/default
+
+If you get a 401 error:
 
     {
       "id": "unauthorized",
@@ -125,9 +129,11 @@
 
 ## Product update testing walkthrough
 
-### Base/Test image setup {.c4 .c19 .c25 .c44}
-
-On your host computer, first install the latest snappy tools:
+### Creating a Product Image
+
+#### Host Setup
+
+Now it is time to create your first product based on Ubuntu Core. On your host computer, first install the latest snappy tools:
 
     sudo add-apt-repository ppa:snappy-dev/tools
     sudo apt-get update
@@ -136,6 +142,8 @@
 
 See [Snappy Getting Started Guide](https://developer.ubuntu.com/en/snappy/start/) for further details.
 
+#### Image Building
+
 Next, you will create an image for RPI2 from the rolling/edge channel, with our test-snap pre-installed:
 
     wget https://spi.canonical.com/assets/test-snap_1_all.snap
@@ -154,9 +162,14 @@
 Then uncompress the downloaded file:
 
     unxz spi-test_pi2.img.xz
-  
+
+When you are working with your real product you will substitute in your custom oem and application snaps. See [OEM snappy package](https://developer.ubuntu.com/en/snappy/guides/oem/) for more information.
+
+#### Provisioning the RPi2
+
 Now, because remotely flashing the Raspberry Pi is still in development, you
-will need to manually flash an SD card with the image.
+will need to manually flash an SD card with the image. We are going to do a walkthrough of this now
+to ensure that you have everything setup correctly.
 
 On the host machine, insert your SD card and determine which device it is (using ```df -h``` or other tools). 
 
@@ -175,57 +188,60 @@
 If the device is not accessible, you can troubleshoot by using a serial
 cable to get a console on the RPi2, see [these instructions](http://elinux.org/RPi_Serial_Connection). Note the pins are the same for RPi1 and RPi2.
 
-### Configure SPI
+### Product and Test Setup
 
 For SPI to generate tests in case of new snap revisions, some configuration needs to be done.
 
-The Manifest will describe how your product is built, and has the basic information that allows SPI to detect changes that affects your product when a new snap revision is available. When this happens, SPI will use the information in the Test Specification to trigger the corresponding tests.
+The Manifest will describe how your product is built, and has the basic information that allows SPI to detect changes that affect your product when a new snap revision is available. When this happens, SPI will use the information in the Test Specification to trigger the corresponding tests.
 
-To create a Manifest, you need to issue an HTTP request specifying the
-following:
+To create a Manifest, you need to issue an HTTP request specifying the following:
 
 -   ```image_name```: the name of the image you will be testing, to relate the Manifest to the Test Specs we will be creating later
--   ```release```: the Snappy release this products aims for
--   ```base_image_reference```: the URL where to download the image
--   ```snaps```: the list of snaps that the product uses
+-   ```release```: the Ubuntu Core release this products aims for (currently "15.04" or "rolling")
+-   ```base_image_reference```: a pointer to the base image, in this case a URL pointing to the image binary
+-   ```snaps```: the list of snaps that that comprise the product
 
 So, in the agent directory execute the following from your computer (where you already authenticated during the lab setup above):
 
     ./api_example.py -X POST config.ini https://spi.canonical.com/orgs/$ORGANIZATION/products/manifests --data '{
         "image_name": "tutorial-raspi2-image",
-        "release": "rolling-core",
+        "release": "rolling",
         "base_image_reference": "https://spi.canonical.com/assets/spi-test_pi2.img.xz",
-        "snaps": [["test-snap.spi-test", 1, false],
-                  ["ubuntu-core.canonical", null, false]]
+        "snaps": [
+            ["ubuntu-core.canonical", null, false],
+            ["test-snap.spi-test", 1, false],
+            ["webdm.canonical", null, false]]
     }'
 
-Note particularly that one of the snaps is the one used for this Tutorial, in version 1; we'll trigger the tests when a new version comes available for it.
-
-Then, create the Test Specification, specifying:
-
--   ```platform```: the platform where image will be installed and test run
--   ```image_name```: the same than we put in the Manifest above
--   ```name```: just a reference so later the system can show you which test this is
+Note "test-snap" is our sample application snap that we'll be using to trigger the tests when a new version becomes available, and we start here with sequence 1 in our base image.
+
+Next you'll define your test scenario via a Test Specification, with the following fields:
+
+-   ```name```: a unique reference to identify tests and their results
+-   ```image_name```: the same that we put in the Manifest above
+-   ```platform```: defines the target device and is used to route tests to the proper agents.
 -   ```test_payload```: information for the test to be run; in this case we put where the tests can be downloaded, and the command to trigger their execution
 
 So, execute the following:
 
     ./api_example.py -X POST config.ini https://spi.canonical.com/orgs/$ORGANIZATION/tests/specs --data '{
+        "name": "Tutorial Example Test Specification",
+        "image_name": "tutorial-raspi2-image",
         "platform": "spi-tutorial-raspi2",
-                "image_name": "tutorial-raspi2-image",
-                "name": "Tutorial Example Test Specification",
-                "test_payload": {
-        "tarball_url": "https://spi.canonical.com/assets/test_tarball.tar.gz",
-        "test_cmd": "./test"
+        "test_payload": {
+            "tarball_url": "https://spi.canonical.com/assets/test_tarball.tar.gz",
+            "test_cmd": "./test"
         }
     }'
 
-At this point SPI is configured and supervising the Store for new
-versions of your snap.
-
-### Trigger/running of actual tests
-
-Now we'll tell SPI manually that a new version of the snap we're using for the tutorial is available:
+At this point SPI is configured for your Product and Tests and will supervise the Store for new
+versions of the snaps listed in your Manifest.
+
+### Your First Test Run
+
+#### Triggering Tests
+
+Now we'll tell the system manually that a new version of the snap we're using for the tutorial is available:
 
     ./api_example.py -X POST config.ini https://spi.canonical.com/orgs/$ORGANIZATION/snap-revisions --data '{
         "name": "test-snap.spi-test",
@@ -234,29 +250,32 @@
 
 In the response there are the ```test_opportunity_id``` and ```image_unique_id``` fields that will be used next, please keep them around.
 
-At this point the SPI has generated a message that is waiting to be consumed by our Agent, and when that message arrives the Agent will try to run the commands to provision, setup and run the tests. For that we need to put useful commands in the config file. So, edit ```config.ini``` and replace the following three fields (the path needs to be absolute, be sure to replace the correct values):
+#### Agent Provisioning Kit Setup
+
+At this point the system has generated a message that is waiting to be consumed by your Agent, and when that message arrives the Agent will try to run the commands to provision, setup and run the tests. Together these scripts are called a "Provisioning Kit", and we have provided a sample kit for this tutorial and as a starting point for your own projects.
+
+So, edit ```config.ini``` and replace the following three fields (the path needs to be absolute, be sure to replace the correct values):
 
     provcommand = PATH_TO_AGENT/rpi2-sample-provkit/provision
     setupcommand = PATH_TO_AGENT/rpi2-sample-provkit/setup
     testcommand = PATH_TO_AGENT/rpi2-sample-provkit/runtest
 
-Next step, then, is to start the Agent to get that message and start running the test. As of this moment, we'd need to set up the Raspberry Pi manually, so the Agent after receiving the test to run will produce some instructions to get an image and burn it into the device, so please follow those instructions and let the Agent know when you're ready (it will wait for you to press Enter).
+Next step, then, is to start the Agent to consume that test opportunity message and start running the test. As remote flashing of the Raspberry Pi is still in development, we'll need to set up the Raspberry Pi manually. After receiving the test to run, the Agent will produce some instructions to get an image and burn it into the device, so please follow those instructions and let the Agent know when you're ready (it will wait for you to press Enter).
 
-So, run:
+Here we go:
 
     ./agent.py --once config.ini
 
 After executing the test, the Agent will automatically retrieve the
-results and send them back to SPI. 
-
-Note that during the provisioning you may get instructions to write the Raspberry Pi's card again; for the case of the tutorial this is not needed, as you already did this step before.
-
-
-### How to check tests results and/or progress
-
-At any time, you can check the progress of any tests generated in the
-system, where they stands (to be run, or already run, etc), checking the
-events in the system:
+results and send them back to the system.
+
+Note that during the provisioning you will be instructed to flash the Raspberry Pi's card again; for the case of the tutorial you may skip this step since you flashed the image earlier during the "Provisioning the RPi2" setup step.
+
+
+#### Checking Test Progress and Results
+
+At any time, you can check the progress of tests generated in the
+system (replace ```<test_opportunity_id>``` with the one you saved from "Triggering Tests" above):
 
     ./api_example.py config.ini \
     https://spi.canonical.com/orgs/$ORGANIZATION/tests/events?test_opportunity_id=<test_opportunity_id>
@@ -268,7 +287,7 @@
     ./api_example.py config.ini \
     https://spi.canonical.com/orgs/$ORGANIZATION/tests/events?image_unique_id=<unique_image_id>
 
-You can see the results produced for all products within an organisation by running:
+You can see the results produced for all products within an organization by running:
 
     ./api_example.py config.ini https://spi.canonical.com/orgs/$ORGANIZATION/tests/events
 
@@ -286,6 +305,5 @@
 
 ### Ubuntu Core update testing
 
-
 ### New Gold Master Candidate Testing