Merge lp:~fginther/ubuntu-ci-services-itself/usage-doc-updates into lp:ubuntu-ci-services-itself

[Francis Ginther]

Add usage documentation to cover creating a launchpad account, creating source packages and other usage updates.

Add usage documentation to cover creating a launchpad account, creating source packages and other usage updates.

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:383
http://s-jenkins.ubuntu-ci:8080/job/uci-engine-ci/412/
Executed test runs:

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/uci-engine-ci/412/rebuild

review: Approve (continuous-integration)

[Chris Johnston (cjohnston)]

On Thu, Mar 13, 2014 at 5:24 PM, Francis Ginther <
<email address hidden>> wrote:

> +* Download a source package of interest
> +
> +.. code-block:: none
> +
> + apt-get download <package_name>
> +
>

This only works if the user is on saucy I believe. Are we guaranteed that
all users will be on saucy?

+Ubuntu CI Engine requests, known as tickets, are created through a command
> line
> +interface.
> +
> +.. code-block:: none
> +
> + python ubuntu-ci create_ticket -t "Ticket name" -d "Ticket description"
> -b 123 -o <email address hidden> -a "foo,bar" -r "baz" -s
> /full/path/to/_source.changes -s /full/path/to/_source.changes
>
>
If the CLI is actually packaged, I don't believe they would need the
'python' portion of the command. How are we handling the ~/.ubuntu-ci
requirement? Unless it's shipped and ready to go with the package, we need
to document something about it.

[Francis Ginther (fginther)]

> On Thu, Mar 13, 2014 at 5:24 PM, Francis Ginther <
> <email address hidden>> wrote:
>
> > +* Download a source package of interest
> > +
> > +.. code-block:: none
> > +
> > + apt-get download <package_name>
> > +
> >
>
> This only works if the user is on saucy I believe. Are we guaranteed that
> all users will be on saucy?

Correct. There are some deeper assumptions in setting up an environment for creating source packages. I'm now considering removing this. If I can't concisely describe the setup in a handful of steps, then it really doesn't belong in this document. Better documentation for generating source packages exists elsewhere, I should just link to that.

> +Ubuntu CI Engine requests, known as tickets, are created through a command
> > line
> > +interface.
> > +
> > +.. code-block:: none
> > +
> > + python ubuntu-ci create_ticket -t "Ticket name" -d "Ticket description"
> > -b 123 -o <email address hidden> -a "foo,bar" -r "baz" -s
> > /full/path/to/_source.changes -s /full/path/to/_source.changes
> >
> >
> If the CLI is actually packaged, I don't believe they would need the
> 'python' portion of the command. How are we handling the ~/.ubuntu-ci
> requirement? Unless it's shipped and ready to go with the package, we need
> to document something about it.

Good point. I need to mention the ~/.ubuntu-ci file because it's not part of the package and needs to be configured based on the deployed system the user is interacting with.

[Andy Doan (doanac)]

93 + python ubuntu-ci

if ubuntu-ci is installed you shouldn't need to prefix with "python"

[lp:~fginther/ubuntu-ci-services-itself/usage-doc-updates]

384. By Francis Ginther on 2014-03-14

Remove the source package tutorial, add details for .ubuntu-ci.

385. By Francis Ginther on 2014-03-14

Remove 'python' from ubuntu-ci command.

[Francis Ginther (fginther)]

This should address the comments:

1) removed python from ubuntu-ci command line.
2) removed mini source package guide
3) added info on the ~/.ubuntu-ci file

review: Needs Resubmitting

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:384
http://s-jenkins.ubuntu-ci:8080/job/uci-engine-ci/416/
Executed test runs:

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/uci-engine-ci/416/rebuild

review: Approve (continuous-integration)

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:385
http://s-jenkins.ubuntu-ci:8080/job/uci-engine-ci/418/
Executed test runs:

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/uci-engine-ci/418/rebuild

review: Approve (continuous-integration)

[Andy Doan (doanac)]

review: Approve

=== modified file 'docs/usage.rst'
--- docs/usage.rst	2014-03-13 18:35:32 +0000
+++ docs/usage.rst	2014-03-14 04:33:31 +0000
@@ -5,12 +5,64 @@
 As the Ubuntu CI Engine evolves through development, the usage will become
 more user friendly and more robust.
 
-Submitting a Ticket
--------------------
-
-CI requests, known as tickets, are created through a command line interface. ::
-
- 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
+Prerequisites
+-------------
+
+The Ubuntu CI Engine current only processes source packages as input. These
+source packages will be uploaded unmodified into a Launchpad PPA.  As a result,
+the source packages used as input must be signed by a user with permission to
+upload to the PPAs used by the Ubuntu CI Engine. These teams will be managed
+through Launchpad team membership granted via a CI team member.
+
+**Launchpad Setup**
+
+Prior to creating a source package to upload and a ticket, a user will need
+setup a Launchpad account and OpenPGP key:
+
+* Create an https://launchpad.net/ account.
+* Create and upload an OpenPGP key to Launchpad. Instructions are available
+  at https://help.launchpad.net/YourAccount/ImportingYourPGPKey.
+
+**Creating a Source Package**
+
+Once the account setup is complete, users can create source packages. A full
+tutorial on creating and modifying source packages are beyond the scope of this
+document. There are many Ubuntu development and packaging guides available
+including:
+
+* http://packaging.ubuntu.com/html/
+* https://wiki.ubuntu.com/UbuntuDevelopment
+
+Configuring the Ubuntu CI Engine Client
+---------------------------------------
+
+The Ubuntu CI Engine is deployed as a cloud service. The client module must be
+configured with a settings file to connect to the service running in the cloud
+and supply the necessary credentials. These settings are saved under the file
+*~/.ubuntu-ci* with the following format:
+
+.. code-block:: none
+
+  auth_url: <nova $OS_AUTH_URL>
+  auth_user: <nova $OS_USERNAME>
+  auth_password: <nova $OS_PASSWORD>
+  auth_tenant_name: <nova $OS_TENANT_NAME>
+  auth_region: <nova $OS_REGION_NAME>
+  ci_url: <URL for the ts-django service>
+
+.. note::
+  All of these settings are obtained by the Ubuntu CI Engine administrator
+  once the services have been deployed to the cloud.
+
+Creating a Ticket
+-----------------
+
+Ubuntu CI Engine requests, known as tickets, are created through a command line
+interface.
+
+.. code-block:: none
+
+  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
@@ -18,17 +70,47 @@
 First Out) order. As the system is limited to processing one ticket at a time,
 it may take multiple hours for a single ticket to be completed.
 
-Parts of a ticket specification
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The input for a ticket is one or more source packages and optionally, a list
-of binary package names to add to or remove from the image that will be
-generated.
+Parts of a ticket submission
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The general input specification for a ticket is one or more source packages and
+a list of binary package names to add to or remove from the image that will be
+generated. These are specified with the appropriate create_ticket arguments.
+The full set of required and optional create_ticket arguments are:
+
+.. code-block:: none
+
+  usage: ubuntu-ci create_ticket [-h] -t TITLE -d DESCRIPTION [-b BUG] -o OWNER
+                                 -a ADD [-r REMOVE] -s SOURCES
+
+  optional arguments:
+    -h, --help            show this help message and exit
+    -t TITLE, --title TITLE
+                          Ticket title
+    -d DESCRIPTION, --description DESCRIPTION
+                          Ticket description
+    -b BUG, --bug BUG     Related bug number
+    -o OWNER, --owner OWNER
+                          Email address of the ticket owner
+    -a ADD, --add ADD     Binaries to be added to the install
+    -r REMOVE, --remove REMOVE
+                          Binaries to be removed from the install
+    -s SOURCES, --sources SOURCES
+                          Path to source.changes files. Source package files
+                          (e.g. source.dsc, source.orig.tar.gz, etc.) are
+                          required to be in the same directory as their
+                          respective source.changes.
+
+.. note::
+  The -t and -d arguments can be specified with a quoted text string. The -a and
+  -r arguments can be used to specify a single package or a list of comma
+  separated packages.
 
 Ticket Defaults
 ~~~~~~~~~~~~~~~
 
-Images are produced from a default source image and series.
+Images are produced from a default source image and series, which is currently
+based on Ubuntu 13.10 (saucy).
 
 Specification of a source package
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -127,5 +209,4 @@
 
   $ subunit-1to2  <subunit.stream | subunit2junitxml >results.xml
 
-This produces a 'results.xml' file suitable for jenkins.
-
+This produces a 'results.xml' file in the junitxml format.