Merge lp:~cjohnston/ubuntu-ci-services-itself/more-ts-docs-updates into lp:ubuntu-ci-services-itself

[Chris Johnston]

Updates of the TS docs

[Francis Ginther (fginther)]

Approve.

review: Approve

=== modified file 'docs/components/ticket-system.rst'
--- docs/components/ticket-system.rst	2014-01-15 21:12:09 +0000
+++ docs/components/ticket-system.rst	2014-01-17 01:40:37 +0000
@@ -1,6 +1,5 @@
-Ticket System (former Project Manager)
-======================================
-
+Ticket System
+=============
 
 Purpose
 *******
@@ -139,16 +138,16 @@
 Tickets
 -------
 
-list
-~~~~
+List tickets
+~~~~~~~~~~~~
 
 List all open tickets.
 
 ::
 
- curl --dump-header - http://162.213.34.2:8000/api/v1/ticket/
+ curl --dump-header - http://localhost:8000/api/v1/ticket/
 
-create_ticket
+Create ticket
 ~~~~~~~~~~~~~
 
 Create a ticket from one or more source package uploads.
@@ -157,46 +156,129 @@
 
  curl --dump-header - -H "Content-Type: application/json" -X POST --data '{"owner": "[e-mail]", "title": "My first ticket", "description": "This if my first ticket. See what it can do", "bug_id": "12345", "added_binaries": "binary-1,binary-2", "removed_binaries": "binary-3,binary-4"}' http://localhost:8000/api/v1/ticket/
 
-get_ticket
+Get ticket
 ~~~~~~~~~~
 
-Return the ticket given its id.
-
-::
-
- curl --dump-header - http://162.213.34.2:8000/api/v1/ticket/1/
-
-get_next_ticket
+*Full ticket*
+
+Returns ALL information about the given ticket.
+
+::
+
+ curl --dump-header - http://localhost:8000/api/v1/fullticket/1/
+
+*Model info*
+
+Return the ticket model info only for the given ticket.
+
+::
+
+ curl --dump-header - http://localhost:8000/api/v1/ticket/1/
+
+Get Next Ticket
 ~~~~~~~~~~~~~~~
 
 Show the current in progress, or the first pending ticket.
 
 ::
 
- curl --dump-header - http://162.213.34.2:8000/api/v1/next/
+ curl --dump-header - http://localhost:8000/api/v1/next/
 
-get_ticket_status
+Get ticket status
 ~~~~~~~~~~~~~~~~~
 
-Get the ticket status.
-
-create_source_package_upload
+Get the status of all tickets or tickets for a specific status. (Mostly for the WebUI)
+
+*All*
+
+::
+
+ curl --dump-header - http://localhost:8000/api/v1/ticketstatus/
+
+*New*
+
+::
+
+ curl --dump-header - http://localhost:8000/api/v1/ticketstatus/?current_workflow_step=100
+
+
+*Package Building*
+
+::
+
+ curl --dump-header - http://localhost:8000/api/v1/ticketstatus/?current_workflow_step=200
+
+*Image Building*
+
+::
+
+ curl --dump-header - http://localhost:8000/api/v1/ticketstatus/?current_workflow_step=300
+
+*Image Testing*
+
+::
+
+ curl --dump-header - http://localhost:8000/api/v1/ticketstatus/?current_workflow_step=400
+
+*Package Publishing*
+
+::
+
+ curl --dump-header - http://localhost:8000/api/v1/ticketstatus/?current_workflow_step=500
+
+*Failed*
+
+::
+
+ curl --dump-header - http://localhost:8000/api/v1/ticketstatus/?current_workflow_step=999
+
+*Complete*
+
+::
+
+ curl --dump-header - http://localhost:8000/api/v1/ticketstatus/?current_workflow_step=1000
+
+Update ticket status
+~~~~~~~~~~~~~~~~~~~~
+
+To be used by the CLI and the lander
+
+::
+
+ curl --dump-header - -H "Content-Type: application/json" -X PATCH --data '{"current_workflow_step": "100", "status": "000"}' http://localhost:8000/api/v1/updateticketstatus/1/
+
+Update subticket status
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To be used by the CLI and the lander
+
+::
+
+ curl --dump-header - -H "Content-Type: application/json" -X PATCH --data '{"current_workflow_step": "100", "status": "000"}' http://localhost:8000/api/v1/updatesubticketstatus/1/
+
+Create source package upload
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+To be used by the CLI
+
 ::
 
  curl --dump-header - -H "Content-Type: application/json" -X POST --data '{"sourcepackage": "/api/v1/sourcepackage/X/", "version": "1.0"}' http://localhost:8000/api/v1/spu/
 
-create_artifact
+Create artifact
 ~~~~~~~~~~~~~~~
 
+Valid types are: "SPU", "RESULTS", "LOGS"
+
 ::
 
- curl --dump-header - -H "Content-Type: application/json" -X POST --data '{"name": "my_artifact", "subticket": "/api/v1/ticket/X/", "reference": "http://path.to/artifact/", "type": "SPU"}' http://localhost:8000/api/v1/artifact/
+ curl --dump-header - -H "Content-Type: application/json" -X POST --data '{"name": "my_artifact", "subticket": "/api/v1/subticket/X/", "reference": "http://path.to/artifact/", "type": "SPU"}' http://localhost:8000/api/v1/artifact/
 
-create_subticket
+Create subticket
 ~~~~~~~~~~~~~~~~
 
+To be used by the CLI
+
 ::
 
  curl --dump-header - -H "Content-Type: application/json" -X POST --data '{"source_package_upload": "/api/v1/spu/X/, "ticket": "/api/v1/ticket/X/, "assignee": "[e-mail]"}' http://localhost:8000/api/v1/subticket/
@@ -205,98 +287,37 @@
 Project
 -------
 
-get_source_package
+Get source package
 ~~~~~~~~~~~~~~~~~~
 
-*return all binary packages*
+return all source packages
 
 ::
 
  curl --dump-header - http://localhost:8000/api/v1/sourcepackage/
 
-add_source_package
+Add source package
 ~~~~~~~~~~~~~~~~~~
 
+This action would be completed by the CLI when it encounters a new source package that the ticket system hasn't had before.
+
 ::
 
  curl --dump-header - -H "Content-Type: application/json" -X POST --data '{"name": "my-package"}' http://localhost:8000/api/v1/sourcepackage/
 
-get_binary_package
+Get binary package
 ~~~~~~~~~~~~~~~~~~
 
-*return all binary packages*
+return all binary packages
 
 ::
 
  curl --dump-header - http://localhost:8000/api/v1/binarypackage/
 
-add_binary_package
-~~~~~~~~~~~~~~~~~~
-
-::
-
- curl --dump-header - -H "Content-Type: application/json" -X POST --data '{"name": "my-package", "sourcepackage": "/api/v1/sourcepackage/1/", "seeded": "False"}' http://localhost:8000/api/v1/binarypackage/
-
-Person - TODO
--------------
-
-add_person
-~~~~~~~~~~
-
-Add a person (or a team) to the database.
-
-*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/
-
-
-get_person
-~~~~~~~~~~
-
-*Return all persons*
-
-::
-
- curl http://localhost:8000/api/v1/person/
-
-*search by name*
-
-::
-
- 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
-
-*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
-
-*show/don't show teams*
-
-::
-
- curl --dump-header - http://localhost:8000/api/v1/person/?is_team=True
- curl --dump-header - http://localhost:8000/api/v1/person/?is_team=False
-
 Models
 ******
 
-Ticket System will be django + REST + Postgres. It will have apps and data models similar to the following.
+Ticket System will be django + REST + Postgres. The phase 0 models are defined below with the proposed future models coded out below that.
 
 Phase 0
 -------
@@ -304,94 +325,35 @@
 sourcepackage
 ~~~~~~~~~~~~~
 
-::
-
- class SourcePackage(models.Model):
-    name = models.CharField(max_length=4096)
+A source package is an existing source package in the Ubuntu archives. A source package record is created when a source package has changes submitted to the ticket system for the first time.
+
+binarypackage
+~~~~~~~~~~~~~
+
+The 'master list' of all binary packages to be tested whenever a change is made. This list can be added to and removed from when creating tickets.
 
 sourcepackageupload
 ~~~~~~~~~~~~~~~~~~~
 
-::
- 
- class SourcePackageUpload(models.Model):
-    sourcepackage = models.ForeignKey("SourcePackage")
-    version = models.CharField(max_length=4096)
-    date = models.DateTimeField()
-    artifact = models.ForeignKey("Artifact")  # Provided by the artifact manager
-
+A 'Source Package Upload' is a file uploaded by the user that is related to the changes being made. It will have a related source package and artifacts.
 
 ticket
 ~~~~~~
 
-A ticket can contain only one active subticket per source package. This
-way we can reference the ticket externally by source package name and ticket
-number.
-
-::
-
- class Ticket(models.Model):
-    WORKFLOW_STEPS = (
-        (PACKAGE_BUILDING, "Package Building"),
-        (IMAGE_BUILDING, "Image Building"),
-        (IMAGE_TESTING, "Image Testing"),
-        (PACKAGE_PUBLISHING, "Package Publishing"),
-    )
-    WORKFLOW_STEP_STATUSES = (
-        (PKG_BUILD_WAITING, "Not Started"),
-        (PKG_BUILD_INPROGRESS, "In Progress"),
-        (PKG_BUILD_DONE, "Completed"),
-        (PKG_BUILD_FAILED, "Failed"),
-        (IMAGE_BUILD_WAITING, "Not Started"),
-        (IMAGE_BUILD_INPROGRESS, "In Progress"),
-        (IMAGE_BUILD_DONE, "Completed"),
-        (IMAGE_BUILD_FAILED, "Failed"),
-        (IMAGE_TESTS_WAITING, "Not Started"),
-        (IMAGE_TESTS_INPROGRESS, "In Progress"),
-        (IMAGE_TESTS_PASSED, "Passed"),
-        (IMAGE_TESTS_FAILED, "Failed"),
-        (PKG_PUBLISHING_DONE, "Completed"),
-        (PKG_PUBLISHING_FAILED, "Failed"),
-    )
-    owner = models.ForeignKey("Person")
-    title = models.CharField(max_length=4096)
-    description = models.TextField()
-    bug_id = models.IntegerField(null=True, blank=True)
-    current_workflow_step = models.CharField(choices=WORKFLOW_STEPS)
-    status = models.CharField(choices=WORKFLOW_STEP_STATUSES)
-    base_image = models.CharField(max_length=20)
+A ticket is created to get a change (or set of changes) into the Ubuntu archive. Creating a ticket allows the changes to be tracked through the processes of package building, image building, image testing and publishing as well as the results to be seen by the user.
 
 subticket
 ~~~~~~~~~
 
-::
-
- class SubTicket(models.Model):
-    WORKFLOW_STEPS = (
-        (PACKAGE_BUILDING, "Package Building"),
-    )
-    WORKFLOW_STEP_STATUSES = (
-        (PKG_BUILD_WAITING, "Not Started"),
-        (PKG_BUILD_INPROGRESS, "In Progress"),
-        (PKG_BUILD_DONE, "Completed"),
-        (PKG_BUILD_FAILED, "Failed"),
-    )
-    current_workflow_step = models.CharField(choices=WORKFLOW_STEPS)
-    status = models.CharField(choices=WORKFLOW_STEP_STATUSES)
-    ticket = models.ForeignKey("Ticket")
-    assignee = models.ForeignKey("Person") 
-    sourcepackageupload = models.ForeignKey("SourcePackageUpload")
-
+Each source package upload that is added to a ticket will have its own subticket. A ticket can contain one of more subtickets. The subticket allows the user to track the progress and results of the package building for each source package upload.
 
 artifact
 ~~~~~~~~
 
-::
- 
- class Artifact(models.Model):
-    type = models.CharField(choices=["test_result", "source_upload", "test_failure_log"]
-    subticket = models.ForeignKey("subticket")
-    reference = models.CharField(max_length=4096)  # Provided by the artifact manager
+Artifacts can be multiple things. When a ticket is initially created, it will have artifacts attached to it which are the source package upload files. Artifacts can also be test results and log files. They can be assigned to a relevant ticket or subticket based on the step of the process.
+
+Future Apps/Models
+------------------
 
 person
 ~~~~~~
@@ -403,10 +365,6 @@
     email = models.EmailField(max_length=200)
     is_team = models.BooleanField(default=False)
 
-
-Future Apps/Models
-------------------
-
 testsuites
 ~~~~~~~~~~
 
@@ -463,3 +421,58 @@
      lp_weblink = models.CharField(max_length=4096)
 
 
+Person API's - TODO
+-------------------
+
+add_person
+~~~~~~~~~~
+
+Add a person (or a team) to the database.
+
+*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/
+
+
+get_person
+~~~~~~~~~~
+
+*Return all persons*
+
+::
+
+ curl http://localhost:8000/api/v1/person/
+
+*search by name*
+
+::
+
+ 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
+
+*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
+
+*show/don't show teams*
+
+::
+
+ curl --dump-header - http://localhost:8000/api/v1/person/?is_team=True
+ curl --dump-header - http://localhost:8000/api/v1/person/?is_team=False