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

[Evan]

Change Snappy to Ubuntu Core. 🔥

https://trello.com/c/c5j3AJfx/1-epic-docs

"Edit naming in the doc to be Ubuntu Core, not Snappy, and Product Integration, not Snappy Product Integration/SPI"

[Thomi Richards (thomir-deactivatedaccount)]

Looks mostly good - I added a few diff comments. Feel free to land whenever you like.

review: Approve

[Celso Providelo (cprov)]

Evan,

I've just confirmed these changes are still relevant for https://spi.staging.canonical.com/assets/tutorial.html. Somehow I thought they were already addressed on the current tutorial, but it's only fixed in the org-less tutorial(2) candidate.

I think we should fix the current document, specially because it will continue to be consulted (and supported) for some time.

I am happy to see this landed when Thomi's comments get addressed. Pre-approving.

review: Approve

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

160. By Evan on 2015-12-04

Merge with trunk.

161. By Evan on 2015-12-04

Remove references to 'Product Integration' and instead use 'Ubuntu Core' or reword to drop the product reference.

162. By Evan on 2015-12-04

s,determine if,ensure, - thanks Thomi.

163. By Evan on 2015-12-04

Fix sentence to drop spurious 'itself'.

164. By Evan on 2015-12-04

Swap around org ID and named ref

165. By Evan on 2015-12-04

dist-upgrade is not needed

166. By Evan on 2015-12-04

Drop 'when a new snap rev is available.'

=== modified file 'docs/tutorial.md'
--- docs/tutorial.md	2015-11-24 21:08:07 +0000
+++ docs/tutorial.md	2015-12-04 23:10:29 +0000
@@ -1,18 +1,17 @@
-Title:   Getting Started with Snappy Product Integration
-Version: 20151030
+Title:   Getting Started with Product Integration in Ubuntu Core
+Version: 20151103
 
-Snappy Product Integration (SPI) is a system for automated integration
-testing of products built upon Ubuntu Core. Once configured, SPI will
-monitor for updates to components of your product and run automated
-tests against target devices to determine if those updates are
-compatible, and allow you to control the flow of those updates to your
-customers.
+Ubuntu Core includes a system for automated integration testing of products
+built upon it. Once configured, this will monitor for updates to components of
+your product and run automated tests against target devices to ensure those
+updates are compatible, and allow you to control the flow of those updates to
+your customers.
 
 This tutorial will guide you step-by-step to create a snap for an application,
 define a product that includes that application, create a laboratory
 environment where integration tests for that product can run, and set up the
-SPI system so that it automatically executes tests in that laboratory when new
-versions of the snap become available.
+product integration system so that it automatically executes tests in that
+laboratory when new versions of the snap become available.
 
 The document is organized as follows:
 
@@ -43,25 +42,26 @@
 -   A 4GB (minimum) Micro SDHC card.
 -   The host computer and Raspberry Pi connected on the same local ethernet network.
 -   Access to the Internet from the host computer.
--   An optional serial USB cable, for debugging the RPI boot sequence.
--   OAuth credentials tied to an SPI Organization. This will be covered below
-    during [Lab setup](#lab-setup).
+-   An optional serial USB cable, for debugging the Raspberry Pi boot sequence.
+-   OAuth credentials tied to an Ubuntu Core Organization. This will be
+    covered below during [Lab setup](#lab-setup).
 
 ## Lab setup
 
-In order to run tests on your product, SPI needs a host computer to serve as a
-bridge between your device and itself. This computer can be as simple as your
-desktop, or part of a full device laboratory.
+The product integration tests are communicated to your device via a host
+computer. This computer can be as simple as your desktop, or part of a full
+device laboratory.
 
 For the purposes of this tutorial, your desktop computer will serve as the
 host and you will use a Raspberry Pi as the product device. The host computer
-will run a small application called the SPI Agent, which will communicate with
+will run a small application called the Agent, which will communicate with
 Canonical's servers and manage integration tests on the Raspberry Pi.
 
 ### Setting up the host computer
 
-You will first need to install and configure the SPI Agent. The most recent
-release of the Agent can always be found at [this location](https://spi.canonical.com/assets/agent.tar.gz).
+You will first need to install and configure the Agent. The most recent release
+of the Agent can always be found at
+[this location](https://spi.canonical.com/assets/agent.tar.gz).
 
 Download and install the Agent from your host computer as follows:
 
@@ -101,11 +101,13 @@
 
 ### Setting up your organization
 
-All users of SPI are each part of an Organization. Your Agents need to be
-registered using a named reference of your physical organization, an Organization ID.
-Organization IDs can only contain lowercase ASCII letters, numbers and hyphens (-). Hyphens can not occur at the start or end of the chosen value.
-Maximum length for an Organization ID is 20 characters.
-For example, if your company name is "Widgets R' Us", you could create an organization ID of "widgets-r-us"
+All users of Ubuntu Core are each part of an Organization. Your Agents need to
+be registered using an Organisation ID, a named reference of your physical
+organization.  Organization IDs can only contain lowercase ASCII letters,
+numbers and hyphens (-). Hyphens can not occur at the start or end of the
+chosen value.  Maximum length for an Organization ID is 20 characters.
+For example, if your company name is "Widgets R' Us", you could create an
+organization ID of "widgets-r-us"
 
 To set up or add users to an Organization:
 
@@ -165,18 +167,19 @@
 
 ## Product update testing
 
-Now it is time to create your first product based on Ubuntu Core. On your host computer, first install the latest Snappy tools:
+Now it is time to create your first product based on Ubuntu Core. On your host
+computer, first install the latest command-line tools:
 
     sudo add-apt-repository ppa:snappy-dev/tools
     sudo apt-get update
-    sudo apt-get dist-upgrade
     sudo apt-get install snappy-tools
 
-See [Snappy Getting Started Guide](https://developer.ubuntu.com/en/snappy/start/) for further details.
+See the [Getting Started Guide](https://developer.ubuntu.com/en/snappy/start/) for further details.
 
 ### Creating a product image
 
-Next, you will create an image for RPI2 from the rolling/edge channel, with our test-snap pre-installed:
+Next, you will create an image for Raspberry Pi from the rolling/edge channel,
+with our test-snap pre-installed:
 
     wget https://spi.canonical.com/assets/test-snap_1_all.snap
     sudo ubuntu-device-flash core rolling --channel edge --oem pi2.canonical --device raspi2_armhf \
@@ -204,7 +207,7 @@
   <div class="panel-body">
      When working with a real product, you will substitute in your custom OEM
      and application snaps. See the <a
-     href="https://developer.ubuntu.com/en/snappy/guides/oem/">Snappy OEM
+     href="https://developer.ubuntu.com/en/snappy/guides/oem/">OEM
      documentation</a> for more information.
   </div>
 </div>
@@ -255,14 +258,18 @@
 
 ### Product and test setup
 
-For SPI to generate tests in case of new snap revisions, some configuration needs to be done.
+To generate tests in response to 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 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.
+The Manifest will describe how your product is built, and has the basic
+information that allows detection of changes which affect your product. When
+this happens, the information in the Test Specification will be used to trigger
+the corresponding tests.
 
 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 Ubuntu Core release this products aims for (currently "15.04-core" or "rolling-core" as known by the Snappy Store)
+-   ```release```: the Ubuntu Core release this products aims for (currently "15.04-core" or "rolling-core" as known by the Ubuntu Core Store)
 -   ```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
 
@@ -300,13 +307,13 @@
         }
     }'
 
-At this point SPI is configured for your product and tests, and will supervise
-the Snappy Store for new versions of the snaps listed in your Manifest.
+At this point your product and tests are configured. The Ubuntu Core Store will
+be supervised for new versions of the snaps listed in your Manifest.
 
 ### Triggering your first test run
 
 Normally the system will automatically detect new revisions of snaps as they
-are published to the Store, and manual steps will not be required. However, for
+are published to the Ubuntu Core Store, and manual steps will not be required. However, for
 the sake of having an update event to work with as part of this tutorial, we
 can manually notify the system that a new version of our snap is available:
 
@@ -414,7 +421,7 @@
 
     ./api_example.py config.ini https://spi.canonical.com/orgs/$ORGANIZATION/tests/events
 
-All tests containing 'RESULT_POSTED' events will have results to be retrieved from SPI:
+All tests containing 'RESULT_POSTED' events will have results to be retrieved:
 
     ./api_example.py config.ini https://spi.canonical.com/orgs/$ORGANIZATION/results