Merge lp:~fginther/ubuntu-ci-services-itself/add-ticket-manager into lp:ubuntu-ci-services-itself

[Francis Ginther]

Revise component specification for the Project Manager, Ticket Manager and Landing Manager and re-factor content to show relationship of sub-functions (components that were 1st class at one time). Fixed some missing links and resolved associated warnings.

Revise component specification for the Project Manager, Ticket Manager and Landing Manager and re-factor content to show relationship of sub-functions (components that were 1st class at one time). Fixed some missing links and resolved associated warnings.

[Joe Talbott (joetalbott)]

review: Approve

=== modified file 'docs/components/landing-manager.rst'
--- docs/components/landing-manager.rst	2013-11-16 10:12:08 +0000
+++ docs/components/landing-manager.rst	2013-11-25 23:34:15 +0000
@@ -17,23 +17,29 @@
 * Project Manager - Provides meta information regarding the project owning a branch (i.e. what trunks to process, which tests to run, etc.). Status updates are sent to the project manager.
 * LP Merge Proposal - MPs are the unit of work managed by the trunk delivering system, if the necessary criteria is in place, the MP will be merged to trunk.
 * Branch/Source Builder - MP branches are dispatched to the builder.
-* PPA - Location where the build will take place
-* Integration Test Runner - Runs the specified test (if any) on the MP packages from the PPA
-* Archive - The packages are copied to the archive from the PPA on successful completion of testing
+* PPA - Location where the package build will take place.
+* PPA Assigneer - Provides a single PPA to perform package builds.
+* Integration Test Runner - Runs the specified test (if any) on the MP packages from the PPA.
+* Archive - The packages are copied to the archive from the PPA on successful completion of testing.
 
 *Development Plan:*
 
 * Define APIs.
 * Deploy an instance.
-* Spawn a build (interact with Branch/Source Builder).
-* Report status (interact with Project Manager and Ticket System).
+* Spawn an MP build (interact with Branch/Source Builder).
+* Allocate a PPA (interact with PPA Assigner).
+* Monitor a PPA for build status.
+* Report status (interact with Project Manager).
 * Initiate integration tests (interact with Integration Test Service).
-* Block trunk.
+* Ensure that trunk has not changed during execution.
+* Merge an MP to trunk.
 * Binary copy a package from PPA to the archive.
 * Monitor archive for status of package.
 * Full end-to-end “Direct merge proposal to trunk” success case.
 * Handle source build failures.
 * Handle binary build failures.
 * Handle integration test failures.
+* Handle trunk changing during execution failures.
+* Handle failure to merge.
 * Handle push to archive failures.
-
+* Handle component failure recovery/restart.

=== modified file 'docs/components/planned.rst'
--- docs/components/planned.rst	2013-11-16 10:12:08 +0000
+++ docs/components/planned.rst	2013-11-25 23:34:15 +0000
@@ -5,9 +5,7 @@
    :maxdepth: 2
 
    project-manager
-   ticket-system
-   ticket-environment-setup
-   test-database
+   ticket-manager
    web-server
    branch-listener
    ppa-assigner

=== modified file 'docs/components/project-manager.rst'
--- docs/components/project-manager.rst	2013-11-16 10:12:08 +0000
+++ docs/components/project-manager.rst	2013-11-25 23:34:15 +0000
@@ -1,24 +1,41 @@
 Project Manager
 ===============
 
+.. toctree::
+   :maxdepth: 2
+
+   ticket-system
+   test-database
+
 *Purpose:*
 
-* Contains project centric knowledge such as location of trunk names of integration tests, point of contact, etc. Also knows status of current MPs being built and a queue of MPs to process.
+* Brains of the CI system. Contains project centric knowledge such as location of trunk names of integration tests, point of contact, etc. Also knows status of current MPs being built and a queue of MPs to process.
+* The project manager maintains the following sets of data:
+  * The history and status of tickets.
+  * The definition and configuration of individual projects.
+  * The test database.
 
 *Deployment:*
 
 * Can run as a juju service.
+* Runs as a persistent service, when it goes down, the engine halts.
 * State needs to serialized whenever it is updated, so that status can be regenerated on a restart.
-* Public facing UI to provide status (or should this export all status to the Web Server)?
-* Most likely a part of the ticket system database
+* Public facing UI is provided by the Web Server.
 
 *Interactions:*
 
+* Ticket Manager - Requests project metadata and provides status updates on tickets active in the CI system.
 * Landing Manager - Requests project metadata and provides updates on status of a branch through the CI system.
+* Web Server - Provides the UI.
 
 *Development Plan:*
 
-* Define backend storage
-* Define API
-* Integrate with Landing Manager
-
+* Define API.
+* Define backend ticket storage.
+* Define backend project specification storage.
+* Define backend test database storage.
+* Integrate with the Web Server.
+* Integrate with the Landing Manager, supply metadata to build and test a single project and generate an automatic low-cost ticket.
+* Handle status updates from the Landing Manager.
+* Integrate with the Ticket Manager to supply metadata to establish a ticket workflow with multiple projects and tests.
+* Handle status updates from the Ticket Manager.

=== modified file 'docs/components/ticket-environment-setup.rst'
--- docs/components/ticket-environment-setup.rst	2013-11-16 10:12:08 +0000
+++ docs/components/ticket-environment-setup.rst	2013-11-25 23:34:15 +0000
@@ -1,5 +1,5 @@
-Ticket Environment Setup (now just a function of the ticket system)
-===================================================================
+Ticket Environment Setup (sub-function of Ticket Manager)
+=========================================================
 
 *Purpose:*
 

=== added file 'docs/components/ticket-manager.rst'
--- docs/components/ticket-manager.rst	1970-01-01 00:00:00 +0000
+++ docs/components/ticket-manager.rst	2013-11-25 23:34:15 +0000
@@ -0,0 +1,55 @@
+Ticket Manager
+==============
+
+.. toctree::
+   :maxdepth: 2
+
+   ticket-environment-setup
+
+*Purpose:*
+
+* Coordinates building, testing and ultimately landing of project feature branches that make up a ticket.
+* Coordinates the landing of multiple components:
+
+ * Ensures that a feature landing is an atomic event
+ * Communicates status as this is done
+ * Provides feedback when something goes wrong and a course of action
+ * Back-out the landing on failure
+
+*Deployment:*
+
+* Can run as a juju service.
+* Needs relationship to Project Manager, Branch Listener, Branch/Source Builder, Image Builder, Integration Test Runner and the Landing Manager.
+* Shouldn’t need to save state, should be able to recreate state upon restart.
+* No public access needed.
+
+*Interactions:*
+
+* Project Manager - Provides meta data regarding the projects and tests to execute for a specific ticket.
+* Branch Listener - Assigned the task of monitoring the feature branches assigened to an MP. New content results in a new build/test cycle.
+* PPA Assigner - Provides two PPAs to perform package builds, one for MPs themselves, another for MPs + trunk.
+* Branch/Source Builder - MP branches are dispatched to the builder.
+* PPAs - Two PPAs are used for performing package builds.
+* Image Builder - Generates up to 3 images to be used for testing: feature branches + base image, feature branches + latest image, feature branches + trunk + latest image.
+* Integration Test Runner - Runs the specified tests on up to 3 images.
+
+*Development Plan:*
+
+* Define APIs.
+* Deploy an instance.
+* Spawn an MP build (interact with Branch/Source Builder).
+* Allocate PPAs (interact with PPA Assigner).
+* Generate feature branches.
+* Submit feature branches to watch (interact with Branch Listener).
+* Report status (interact with Project Manager).
+* Return PPAs.
+* Build an image (interact with Image Builder).
+* Initiate integration tests (interact with Integration Test Service).
+* Implement the "Land Now" button. Dispatch individual trunk merge requests (interact with Landing Manager).
+* Full end-to-end “Workflow II A: feature branch/transitions/fix involving multiple components” success case.
+* Handle source build failures.
+* Handle binary build failures.
+* Handle image build failures.
+* Handle integration test failures.
+* Handle landing failures.
+* Handle component failure recovery/restart.

=== modified file 'docs/components/ticket-system.rst'
--- docs/components/ticket-system.rst	2013-11-16 10:12:08 +0000
+++ docs/components/ticket-system.rst	2013-11-25 23:34:15 +0000
@@ -21,13 +21,6 @@
  * Clear indication of merge/build/test failures and where the failure occurred, make it obvious to developers what a corrective course of action should be
  * Provide a means to execute a landing when all criteria have passed
 
-* Coordinates the landing of multiple components:
-
- * Ensures that a feature landing is an atomic event
- * Communicates status as this is done
- * Provides feedback when something goes wrong and a course of action
- * Back-out the landing on failure
-
 * Provides ticket management:
 
  * list and status of all tickets

=== modified file 'docs/components/web-server.rst'
--- docs/components/web-server.rst	2013-11-16 10:12:08 +0000
+++ docs/components/web-server.rst	2013-11-25 23:34:15 +0000
@@ -11,11 +11,11 @@
 *Deployment:*
 
 * Can run as a juju service.
-* Needs a relationship to the Ticket System and/or Project Manager.
-* Has no internal state, just provides a view to the data in the Ticket System.
+* Needs a relationship to the Project Manager.
+* Has no internal state, just provides a view to the data in the Project Manager.
 * Provides public access with authorization to view private data.
 
 *Interactions:*
 
-* Ticket System - provides an interface for working with tickets and providing latest status.
+* Project Manager - provides an interface for working with tickets and providing latest status.
 

=== modified file 'docs/index.rst'
--- docs/index.rst	2013-11-18 21:21:22 +0000
+++ docs/index.rst	2013-11-25 23:34:15 +0000
@@ -11,7 +11,9 @@
 .. toctree::
    :maxdepth: 2
 
+   ticket
    components
+   api
    sequence
    risks
    timeline