Merge lp:~ev/tanuki-agent/red-pen into lp:tanuki-agent

[Evan]

🎄🎁🎅❄️

[lp:~ev/tanuki-agent/red-pen]

169. By Evan on 2015-12-22

Rework a few sentences.

Unmerged revisions

169. By Evan on 2015-12-22

Rework a few sentences.

168. By Evan on 2015-12-22

Ubuntu Core, not The Ubuntu Core.

167. By Evan on 2015-12-22

Merge with trunk.

=== modified file 'docs/tutorial-products.md'
--- docs/tutorial-products.md	2015-12-22 20:06:06 +0000
+++ docs/tutorial-products.md	2015-12-22 22:29:41 +0000
@@ -4,9 +4,9 @@
 Ubuntu Product Integration is a system for automated integration
 testing of products built upon Ubuntu Core.
 
-The system is designed to facilitate Product testing for both Gold
+It is designed to facilitate Product testing for both Gold
 Master image releases and ongoing update testing, allowing Product
-owners to control updates to devices in the field. The system will
+owners to control updates to devices in the field. It will
 monitor the components of your product and dispatch tests when new updates
 are present, prior to those updates being made available to end users.
 
@@ -20,7 +20,8 @@
 
 -   **[What you will need:](#what-you-will-need)** A description of everything needed to complete the tutorial.
 -   **[Lab setup:](#lab-setup)** Create and configure your own laboratory.
--   **[Gold Master Candidate Testing:](#gold-master-candidate-testing)** Testing of Product images composed from the stable channel, to support releasing Gold Master Images.
+-   **[Gold Master candidate testing:](#gold-master-candidate-testing)**
+    Testing of Product images composed from the stable channel, to support releasing Gold Master images.
 -   **[Product update testing:](#product-update-testing)** Testing of software updates prior to releasing them to customers.
 -   **[First-boot update testing:](#first-boot-update-testing)** First-boot update testing.
 
@@ -387,10 +388,17 @@
 
 ### First test run
 
-This test will be what is called a Gold Master (GM) Candidate test. It is triggered by a change to any of the component snaps in the monitored ```base``` channel defined in the Test Specification (stable in this case). The server will generate a Test Opportunity that instructs the provisioning kit script to compose a new GM candidate image from the Product's snaps, using the current revisions published in the base channel, provision that image, and then run tests against it. Later chapters of the tutorial will discuss additional testing scenarios.
+This test will be what is called a Gold Master (GM) candidate test. It is
+triggered by a change to any of the component snaps in the monitored ```base```
+channel defined in the Test Specification (i.e. "stable"). The server will
+generate a Test Opportunity that instructs the provisioning kit script to
+compose a new GM candidate image from the Product's snaps, using the current
+revisions published in the base channel, provision that image, and then run
+tests against it. Later chapters of the tutorial will discuss additional
+testing scenarios.
 
 When we first defined our Test Specification, the system generated a
-new Test Opportunity to test the initial Gold Master Candidate image,
+new Test Opportunity to test the initial Gold Master candidate image,
 since that combination of snaps in the ```base``` channel had not yet been tested.
 
 Further GM tests will be automatically generated each time a component snap is updated in the ```base``` channel and are not optional.
@@ -491,7 +499,7 @@
 Logs containing the output and errors of the provisioning kit's scripts are always stored in ```logs/```.
 Saving those logs and any artifacts the provisioning kit creates is the responsibility of your test command.
 
-The example provisioning kit will create a tarball with the test opportunity, the test result
+The example provisioning kit will create a tarball with the Test Opportunity, the test result
 and all the provisioning kit logs, using this code:
 
     ARTIFACTS = [
@@ -533,7 +541,7 @@
 testing of Gold Master candidate images, it's time to think about the
 lifecycle of your product once it is delivered to a customer.
 
-The Ubuntu Core is designed to provide transactional updates for
+Ubuntu Core is designed to provide transactional updates for
 both system components and applications. A major advantage of using
 the Product Integration system is to enable testing of those updates
 prior to releasing them into the wild.
@@ -623,21 +631,30 @@
 
 ## 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 images, new Test Opportunities are generated for the candidate
+Gold Master. This creates additional product base images, which are then used
+for testing updates.
+
+The update tests will always be created using the latest base image for the
+product. If you release images, you will also need to test the upgrade path
+from those images in the field. This is handled automatically. All you need is
+to mark the Product Base Image as released, and the update tests will be
+generated using not only the latest base image, but also all those that were
+ever released (until you deactivate them).
+
+You can list all the Product Base Images for a given product with the following
+command:
 
     ./api_example.py -X GET config.ini https://spi.canonical.com/products/$PRODUCT_ID/baseimages
 
-To mark any of those as released, just do:
+To mark any of those as released, simply run:
 
     ./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:
+After this step, that Product Base Image will be used in the update tests. You
+can deactivate a Product Base Image from being used in update tests by running:
 
     ./api_example.py -X PUT config.ini https://spi.canonical.com/products/$PRODUCT_ID/baseimages/<baseimage_id> --data '{
         "active": false