Merge lp:~cjohnston/ubuntu-ci-services-itself/generic-doc-fixes into lp:ubuntu-ci-services-itself

[Chris Johnston]

Misc doc fixes across the board

Just general doc fixes across the board

[Francis Ginther (fginther)]

Thanks for the fixes.

review: Approve

=== modified file 'docs/api/initial-request.rst'
--- docs/api/initial-request.rst	2014-01-16 22:29:43 +0000
+++ docs/api/initial-request.rst	2014-01-24 18:34:54 +0000
@@ -10,7 +10,7 @@
 
 ::
 
- make_request autopilot_1.5~dev.1_source.changes --addpkgs python-autopilot python3-autopilot
+ python ubuntu-ci create_ticket -t "Ticket name" -d "Ticket description" -b 123 -o [e-mail] -a "foo,bar" -r "baz" -s /full/path/to/_source.changes -s /full/path/to/_source.changes
 
 CLI -> Ticket System
 --------------------
@@ -264,14 +264,14 @@
 -----------------------
 
 The lander provides progress to the ticket system through the ticket
-system's progress api:
+system's progress API:
 
 ::
 
  TBD
 
 Completion of a build is provided to the ticket system through the ticket
-system's progress api:
+system's progress API:
 
 ::
 
 
=== modified file 'docs/components/branch-source-builder.rst'
--- docs/components/branch-source-builder.rst	2014-01-17 20:11:51 +0000
+++ docs/components/branch-source-builder.rst	2014-01-24 18:34:54 +0000
@@ -22,7 +22,7 @@
 ************
 
 * Lander sends a "build_source" request to the service (this includes swift
-  urls from the data-store on what to build)
+  URLs from the data-store on what to build)
 
 * A request is placed in the queue (at each step below, the progress_trigger
   will be called to notify of status changes).
@@ -46,12 +46,12 @@
 
 Request a PPA build of the provided sources.
 
-*Url Pattern*
+*URL Pattern*
 
   http://bsbuilder-url:8080/api/v1/build_source (HTTP POST)
 
 *Parameters*
-  * source_packages: An array of data-store URL's containing all of the
+  * source_packages: An array of data-store URLs containing all of the
     source package files.
   * ppa: The PPA allocated by the ppa-assigner for this operation.
   * progress_trigger: A string used to create a dedicated message queue
@@ -116,7 +116,7 @@
 Useful for debug and monitoring. This method will return information like
 the number of worker queues and if they are busy or not.
 
-*Url Pattern*
+*URL Pattern*
 
   http://bsbuilder-url:8080/api/v1/status (HTTP GET)
 
 
=== modified file 'docs/components/existing-pieces.rst'
--- docs/components/existing-pieces.rst	2014-01-21 15:09:33 +0000
+++ docs/components/existing-pieces.rst	2014-01-24 18:34:54 +0000
@@ -16,7 +16,7 @@
 
 **Project Manager**
 
-* Project specific configuration - We are doing this now with lp:cupstream2distro-config but with a very jenkins focused implementation.
+* Project specific configuration - We are doing this now with lp:cupstream2distro-config but with a very Jenkins focused implementation.
 
 **Test Runner**
 
@@ -25,7 +25,7 @@
 
 **Image Building**
 
-* Didier has done this manually for ISO images, using a squash FS process. Need to automate this and modify to work with touch images (which have an ubuntu and platform specific component). (takes about 15 minutes)
+* Didier has done this manually for ISO images, using a squash FS process. Need to automate this and modify to work with touch images (which have an Ubuntu and platform specific component). (takes about 15 minutes)
 
 **Ubuntu CD Image & Germinate**
 
 
=== modified file 'docs/components/image-builder.rst'
--- docs/components/image-builder.rst	2014-01-21 14:56:40 +0000
+++ docs/components/image-builder.rst	2014-01-24 18:34:54 +0000
@@ -12,7 +12,7 @@
 Deployment
 ----------
 
-* Can run as a juju service.
+* Can run as a Juju service.
 * Needs relationship to the Lander and the Data Store.
 * Operations are transient, no need to save state.
 * Will need to have some configuration data though, in particular, for
@@ -48,7 +48,7 @@
   * base_image : {"image_type": IMAGE_TYPE, "url_list": [...], "series": SERIES}
 
     * A json object containing the image_type (cloud for now), list of
-      URLs pointing to the image artifact(s), and the ubuntu series
+      URLs pointing to the image artifact(s), and the Ubuntu series
       name.
       
   * ppa_list : [...]
 
=== modified file 'docs/components/lander.rst'
--- docs/components/lander.rst	2014-01-21 15:09:33 +0000
+++ docs/components/lander.rst	2014-01-24 18:34:54 +0000
@@ -26,7 +26,7 @@
 Phase 0
 -------
 
-* Can run as a juju service.
+* Can run as a Juju service.
 * Needs relationship to Ticket System, PPA Assigner, Branch/Source Builder,
   Image Builder and Test Runner.
 * No public access needed.
@@ -109,27 +109,27 @@
 
 A Lander service handles the workflow by using Jenkins to schedule individual
 tasks. When a request is received to the Lander from the Ticket System, it
-triggers the master jenkins job with the request parameters. The master job
+triggers the master Jenkins job with the request parameters. The master job
 then triggers a series of child jobs to execute the workflow.
 
 The child jobs themselves execute a service handler. The service handler is
 responsible for setting up the progress queue and triggering the service
 via its REST API.  As the service handler runs, it outputs the progress updates
-it receives to the console (to be viewed via jenkins) and pushes the progress
+it receives to the console (to be viewed via Jenkins) and pushes the progress
 update to the Ticket System.
 
 When the service completes, the service handler closes with a return code
 matching the status of the service itself. The result data from the service is
-archived as a jenkins artifact. That data is combined with the existing set of
-job parameters to be used as input to the next jenkins child job.
+archived as a Jenkins artifact. That data is combined with the existing set of
+job parameters to be used as input to the next Jenkins child job.
 
 Only one master job may execute at a time. If additional build requests are
-received, they will be queued by jenkins.
+received, they will be queued by Jenkins.
 
 The Lander supplies regular notification events to the Ticket System while a
 job is executing. There are no notifications sent when the service is idle.
 
-The Lander archives the jenkins console logs and the archived results of each
+The Lander archives the Jenkins console logs and the archived results of each
 job to the data store.
 
 Future
@@ -151,7 +151,7 @@
 Schedules a new request for building source packages and creation and test of
 an image.
 
-*Url Pattern*
+*URL Pattern*
 
   http://lander-url:8080/api/v1/execute_request (HTTP POST)
 
 
=== modified file 'docs/components/planned.rst'
--- docs/components/planned.rst	2014-01-14 02:44:54 +0000
+++ docs/components/planned.rst	2014-01-24 18:34:54 +0000
@@ -5,7 +5,6 @@
    :maxdepth: 2
 
    ticket-system
-   ticket-manager
    web-server
    branch-listener
    ppa-assigner
 
=== modified file 'docs/components/queue-service.rst'
--- docs/components/queue-service.rst	2013-12-09 20:06:06 +0000
+++ docs/components/queue-service.rst	2014-01-24 18:34:54 +0000
@@ -4,7 +4,7 @@
 Purpose
 *******
 
-Provides a generic queue service for the entire CI engine. Common uses are:
+Provides a generic queue service for the entire CI Engine. Common uses are:
 
  * Task queues to manage work between a service accepting requests and a pool
    of workers to actually execute the request.
 
=== modified file 'docs/components/test-runner.rst'
--- docs/components/test-runner.rst	2014-01-21 16:10:57 +0000
+++ docs/components/test-runner.rst	2014-01-24 18:34:54 +0000
@@ -10,7 +10,7 @@
 Future
 ======
 
-Expands upon phase 0 by allowing a set of ppas and additional packages to be
+Expands upon phase 0 by allowing a set of PPAs and additional packages to be
 added before running the tests, support using autopilot on a touch device,
 perform a custom test (TBD), support executing tests on bare metal.
 
@@ -85,7 +85,7 @@
 
 * Setup an instance from the image builder url
 * Run the dep8 tests
-* Collecte the artifacts
+* Collect the artifacts
 * Send test results and artifacts to the lander (via the data store).
 
 Future
 
=== modified file 'docs/components/ticket-system.rst'
--- docs/components/ticket-system.rst	2014-01-21 19:36:04 +0000
+++ docs/components/ticket-system.rst	2014-01-24 18:34:54 +0000
@@ -442,14 +442,14 @@
 
 ::
 
- curl --dump-header - -H "Content-Type: application/json" -X POST --data '{"name": "Chris Johnston", "email": "[e-mail]", "is_team": "False"}' http://localhost:8000/api/v1/person/
+ curl --dump-header - -H "Content-Type: application/json" -X POST --data '{"name": "Chris Johnston", "email": "[e-mail]", "is_team": "False"}' http://localhost:8000/api/v1/person/
 
 
 *team*
 
 ::
 
- curl --dump-header - -H "Content-Type: application/json" -X POST --data '{"name": "Canonical CI Engineering", "email": "[e-mail]", "is_team": "True"}' http://localhost:8000/api/v1/person/
+ curl --dump-header - -H "Content-Type: application/json" -X POST --data '{"name": "Canonical CI Engineering", "email": "[e-mail]", "is_team": "True"}' http://localhost:8000/api/v1/person/
 
 
 get_person
@@ -465,19 +465,19 @@
 
 ::
 
- curl --dump-header - http://localhost:8000/api/v1/person/?name__exact=Chris%20Johnston
- curl --dump-header - http://localhost:8000/api/v1/person/?name__iexact=chris%20johnston
- curl --dump-header - http://localhost:8000/api/v1/person/?name__startswith=Chris
- curl --dump-header - http://localhost:8000/api/v1/person/?name__istartswith=chris
+ curl --dump-header - http://localhost:8000/api/v1/person/?name__exact=My%20Name
+ curl --dump-header - http://localhost:8000/api/v1/person/?name__iexact=my%20name
+ curl --dump-header - http://localhost:8000/api/v1/person/?name__startswith=My
+ curl --dump-header - http://localhost:8000/api/v1/person/?name__istartswith=my
 
 *search by email*
 
 ::
 
- curl --dump-header - http://localhost:8000/api/v1/person/?email__exact=[e-mail]
- curl --dump-header - http://localhost:8000/api/v1/person/?email__iexact=[e-mail]
- curl --dump-header - http://localhost:8000/api/v1/person/?email__startswith=chris
- curl --dump-header - http://localhost:8000/api/v1/person/?email__istartswith=Chris
+ curl --dump-header - http://localhost:8000/api/v1/person/?email__exact=[e-mail]
+ curl --dump-header - http://localhost:8000/api/v1/person/?email__iexact=[e-mail]
+ curl --dump-header - http://localhost:8000/api/v1/person/?email__startswith=user
+ curl --dump-header - http://localhost:8000/api/v1/person/?email__istartswith=User
 
 *show/don't show teams*
 
 
=== modified file 'docs/introduction.rst'
--- docs/introduction.rst	2014-01-23 19:06:13 +0000
+++ docs/introduction.rst	2014-01-24 18:34:54 +0000
@@ -28,12 +28,12 @@
 
 The essiential set of Phase 0 features include:
 
- * CI from debian source packages.
+ * CI from Debian source packages.
  * Building of binary packages and complete images.
  * Tests are executed on the produced image.
  * Tests are defined via autopackage testing.
  * Results are archived and retrieved via a web interface.
- * A micro-service oriented architecture deployed in an openstack cloud
+ * A micro-service oriented architecture deployed in an OpenStack cloud
    environment.
 
 Constraints
@@ -49,7 +49,7 @@
  * Build and test results and logs are provided as raw artifacts.
  * Source packages are used is input.
  * Binary packages and images are built from a default series and image.
- * Openstack cloud images are produced and used for testing.
+ * OpenStack cloud images are produced and used for testing.
  * Tests are limited to autopackage tests defined in the source packages.
 
 Future Phases
 
=== modified file 'docs/ticket.rst'
--- docs/ticket.rst	2013-11-19 19:13:56 +0000
+++ docs/ticket.rst	2014-01-24 18:34:54 +0000
@@ -20,15 +20,15 @@
 * knowing where we stands on all those feature branches and sources compared to latest in distro (if the source package isn't the latest version in the development version anymore)
 * what MP are pending against this ticket, meaning against all attached feature branches.
 * what delta do we have between the various feature branches in this ticket and their corresponding trunks.
-* knowing if we are mergeable or not against those trunks. If we can merge at a T time (and tests are all passing), propose a way to merge trunks easily into those branches.
+* knowing if we are able to merge or not against those trunks. If we can merge at a T time (and tests are all passing), propose a way to merge trunks easily into those branches.
 * after getting the progress on their build, attaching latest available specific image (3 images per ticket): feature branch + fixed image number, feature branch + latest available image, trunk + feature branch merged + latest available image.
 * knowing what latest image number is available, be able to change with it if test on latest image passed.
 * getting tests progress while they are run dynamically. Represents them clearly against those previous 3 image tests
 * ensuring that involved parties like core-devs and design team are involved if the ticket needs their review. A packaging change will require core-devs to ack their change. The design team will be in the process if there is a design change involved. Those should work through credentials.
 * CI general health and global warnings if needed
 * status on the corresponding components health
-* gives an easy way once all those criterias are met (third-party acking, everything built and all tests passing) to give a "go" to the engine to deliver those different trunks.
-* show the progress on the merging back to trunk, building packages there, tests passing, migration in UNAPPROVED/NEW, -proposed, release pocket and close the ticket completely once the next image is kicked in. Demonstrate explicitely when something is blocking there the whole pipeline for other delivery.
+* gives an easy way once all those criteria are met (third-party acking, everything built and all tests passing) to give a "go" to the engine to deliver those different trunks.
+* show the progress on the merging back to trunk, building packages there, tests passing, migration in UNAPPROVED/NEW, -proposed, release pocket and close the ticket completely once the next image is kicked in. Demonstrate explicitly when something is blocking there the whole pipeline for other delivery.
 
 **Tickets interactions**
 
@@ -39,7 +39,7 @@
 Finally, in this global view, we want to show the health of all projects:
 
 * seeing all components (projects/branches) that we have in the CI system with global/general metadata (what test environment is going to be used, what tests are associated with that components, number of tickets opened against them and so on)
-* giving a view for the managers to see what ticket their team are working on, and what's the progress on them as well as global status (build/tests/mergeable to trunk).
+* giving a view for the managers to see what ticket their team are working on, and what's the progress on them as well as global status (build/tests/ability to merge to trunk).
 * if a direct commit to trunk blocked the project and that's the only way to fix it back (another direct commit to trunk), surface that. All other tickets being blocked by that state (as touching that same component) should reflect that info as well.
 * when tickets are expected to be delivered (based on the ETA), so that we can identify hot spots (times where a lot of landing will happen simultaneously and will clash) and try to shuffle them around to not having them in one landing (eventually by a global override on all tickets)
 * a single point to see across all projects where different teams need to assess/review before the delivery takes place (pending packaging changes triggering a core-dev review, design review needed)
 
=== modified file 'docs/usage.rst'
--- docs/usage.rst	2014-01-23 19:06:13 +0000
+++ docs/usage.rst	2014-01-24 18:34:54 +0000
@@ -10,7 +10,7 @@
 
 CI requests, known as tickets, are created through a command line interface. ::
 
- make_request my_source_package_1.0.1_source.changes --addpkgs my_binary_package
+ python ubuntu-ci create_ticket -t "Ticket name" -d "Ticket description" -b 123 -o [e-mail] -a "foo,bar" -r "baz" -s /full/path/to/_source.changes -s /full/path/to/_source.changes
 
 This returns a ticket ID which can later be used to monitor and check for
 results. Once the ticket is created, the Ubuntu CI Engine does the rest. The
@@ -33,7 +33,7 @@
 Specification of a source package
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-A source package is a standard debian source package which may optionally
+A source package is a standard Debian source package which may optionally
 contain dep8 autopackage tests. If autopackage tests are defined, they will
 be used to validate the image that is produced. All tests must pass for a
 ticket to complete CI successfully.