Initial draft of block jira project workflow page.

Observatory-Control-System/BLOCKS/block-jira-project-workflow.rst

@@ -0,0 +1,116 @@
+.. This is a template for operational procedures. Each procedure will have its own sub-directory. This comment may be deleted when the template is copied to the destination.
+
+.. Review the README in this procedure's directory on instructions to contribute.
+.. Static objects, such as figures, should be stored in the _static directory. Review the _static/README in this procedure's directory on instructions to contribute.
+.. Do not remove the comments that describe each section. They are included to provide guidance to contributors.
+.. Do not remove other content provided in the templates, such as a section. Instead, comment out the content and include comments to explain the situation. For example:
+	- If a section within the template is not needed, comment out the section title and label reference. Include a comment explaining why this is not required.
+    - If a file cannot include a title (surrounded by ampersands (#)), comment out the title from the template and include a comment explaining why this is implemented (in addition to applying the ``title`` directive).
+
+.. Include one Primary Author and list of Contributors (comma separated) between the asterisks (*):
+.. |author| replace:: *Erik Dennihy*
+.. If there are no contributors, write "none" between the asterisks. Do not remove the substitution.
+.. |contributors| replace:: *none*
+
+.. This is the label that can be used as for cross referencing this procedure.
+.. Recommended format is "Directory Name"-"Title Name"  -- Spaces should be replaced by hyphens.
+.. Each section should includes a label for cross referencing to a given area.
+.. Recommended format for all labels is "Title Name"-"Section Name" -- Spaces should be replaced by hyphens.
+.. To reference a label that isn't associated with an reST object such as a title or figure, you must include the link an explicit title using the syntax :ref:`link text <label-name>`.
+.. An error will alert you of identical labels during the build process.
+
+.. _BLOCK-observations:
+
+###################
+BLOCK JIRA Workflow
+###################
+
+The Rubin Observatory uses observing blocks to design, plan, execute, and track tasks at the summit which require data taking.
+These tasks range from pure engineering (e.g. closed-dome TMA velocity tests) to science-driven surveys. 
+In most cases, the planning and execution of such tasks must take place on a much shorter timescale than the analysis of the data that is collected, necessitating a separate JIRA project and workflow. 
+This workflow is captured in the BLOCK Project, and described in detail here. 
+
+BLOCK Jira Project Description
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. figure:: _static/BLOCK_Jira_workflow.png
+    :name: BLOCK Jira Project Workflow
+    :width: 621
+    :height: 422
+
+    A block diagram of the workflow contained in the BLOCK Jira project.
+
+End states
+------------
+The end states are the ultimate destination of a reported ticket.
+When a ticket reaches one of these states, is will no longer be considered for scheduling.
+We start by explaining these states because they are referenced throughout the remainder of the document, specifically when describing state transitions.
+
+- ``Done``: All work required to complete the observing block has been Done. There is no current plan to repeat the task. 
+
+- ``Invalid``:  The requested observing block is no longer valid, was filed by mistake, or has been superseded by another block or other events.
+
+There are multiple ways that tickets reach these states, which are explained in the sections below.
+The ``Invalid`` and ``Duplicate`` state is special because it can be transitioned to from any active state in the workflow.
+
+Both ``Invalid`` and ``Done`` allow transition out of these states, which is to return to the ``Proposed`` state and start the workflow over again.
+This transition should be rare. 
+It is reserved for cases when a job is erroneously transitioned to a completed state, or a later analysis of the observing task deems it was not satisfactorily completed. 
+The ticket is then transitioned to ``Proposed`` so it can be prepared and prioritized accordingly by a Commissioning Science Team.
+
+Active states
+-------------
+This section describes each of the active states as well as any transition from that state to another.
+
+- ``Proposed:`` This is the default state that a ticket enters when it is initially filed. 
+  By default, the ticket is left unassigned. 
+  The Commissioning Scientist team is responsible for the initial assessment and assignment of the observing task. 
+  New ticket in the ``Proposed`` state will be reviewed and assigned on a weekly basis (or twice weekly) during one of several planning meetings.
+  The reporter is not responsible for alerting anyone to new ticket creation, but a message on the #sitcom-observing-blocks slack channel is recommnded. 
+  Once the ticket has been assigned to a member of the Commissioning Science team, it will be transitioned to ``Preparation``.
+
+    - *Transition to* ``Preparation``: An initial assessment of the observing task will be done during the weekly planning meeting by the Commissioning Science team. 
+      This initial assessment will include a discussion of work needed to prepare the task, a decision on the priority of the task, and an assignment to a member of the Commissioning Science team for preparation.  
+      Once the ticket has been assigned it can be transitioned to the ``Preparation`` state. 
+
+
+- ``Preparation``: This state describes a task that is currently being prepared for execution at the summit. 
+
+  At this stage, the assignee is expected to work with the proposer to prepare the task for execution at the summit. 
+  The work required in this state includes:
+  - A decision on the best method to execute the observing block (e.g. JSON BLOCK, SAL Script, etc) by the Proposer and Assignee. 
+  - Preparation of the observing task (e.g. write a new JSON BLOCK) by the Proposer and Assignee.   
+  - Testing and validation of the observing task to the extent possible on one of the Test Stands by the Assignee.   
+  - A review of the ticket description for any missing instructions or information (see section below) by the Assignee. 
+  - Deployment of any necessary components/changes at the Summit (e.g. JSON BLOCK) by the Assignee. 
+
+  - *Transition to* ``Ready``: Once all of the steps above have been completed, the Assignee is responsible for transitioning the ticket to Ready. 
+
+  - *Transition to*  ``Proposed``: After initial assignee assessment if the work cannot be completed by the assignee in a timely manner in accordance with the observing task priority, it can be returned to ``Proposed`` for re-assignment. 
+
+- ``Ready``: This state is reserved for observing tasks which have been prepared, tested, reviewed, and deployed at the summit and are ready for execution.
+
+    While in the ``Ready`` state, a task can be added to the plan at any time. 
+    Tasks will be planned for observation in accordance with the priority they were assigned in the ``Proposed`` state. 
+    A review of the tasks which are in the ``Ready`` state is to be carried out as part of the regular Commissioning Science planning meetings. 
+    The work required in this state includes:
+    - Planning of the task for execution by the Commissioning Science team. 
+    - Execution of the task at the Summit.
+    - Review of the data and assessment of task completion by the Proposer and Assignee. 
+
+    - *Transition to* ``Preparation``: If an issue is found with the observing task after it has been transitioned to ``Ready``, it may be transitioned back to ``Preparation``.
+      This transition could be triggered by either the Assignee, the Proposer, or the user responsible for executing the task on the Summit. 
+
+    - *Transition to* ``Done``: If the task has been executed and the data collected deemed satisfactory by the ``Proposer`` and there is no need to repeat the test, 
+      it can be transitioned to ``Done`` and removed from further planning consideration. 
+
+BLOCK Ticket Management Process
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+BLOCK tickets are expected to be the source of instructions for observing tasks requiring execution at the summit. 
+
+
+Contact Personnel
+^^^^^^^^^^^^^^^^^
+
+This procedure was last modified |today|.
+
+This procedure was written by |author|. The following are contributors: |contributors|.