diff --git a/Daytime-Nighttime-Interactions/block-observations.rst b/Daytime-Nighttime-Interactions/block-observations.rst new file mode 100644 index 00000000..04b33113 --- /dev/null +++ b/Daytime-Nighttime-Interactions/block-observations.rst @@ -0,0 +1,138 @@ +.. 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 `. +.. An error will alert you of identical labels during the build process. + +.. _BLOCK-observations: + +########################## +BLOCK Observation Planning +########################## + +The Rubin Observatory + +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. + Note that the transition labels in this diagram describe the process and do not exactly match the names used by the OBS Jira project itself. + +End states +------------ +The end states are the ultimate destination of a reported ticket. +When a ticket reaches one of these states, is it considered to be resolved and will no longer be actively managed by the Fault Handling Management process. +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 address the issue has been completed. + +- ``Cancelled``: The reported issue is no longer valid, was filed by mistake, or has been superseded by another ticket or other events. + +- ``Transferred``: The issue has been deemed non-critical to immediate operations and has been moved to a subsystem for consideration and/or implementation. + +- ``Duplicate``: This is a repeat reporting of an already in-process ticket. + Work on the issue should proceed in the original ticket. + +There are multiple ways that tickets reach these states, which are explained in the sections below. +The ``Cancelled`` and ``Duplicate`` states are special because they can be transitioned to from any active state in the workflow. + +There is one transition out of these states, which is from the ``Done`` state to the ``Reported`` state. +This transition should be rare. +It is reserved for cases when a job is in a completed state, but either the exact error occurs again, or someone deems it is not satisfactorily completed. +The ticket is then transitioned to ``Reported`` so it can be triaged and prioritized accordingly by a Triage manager. + + +Active states +------------- +This section describes each of the active states as well as any transition from that state to another. + +- ``Reported:`` This is the default state that a ticket enters when it is initially filed. + Details on ticket creation on the fields are found in the page on :ref:`Daytime-Nighttime-Interactions-fault-reporting`. + By default, the ticket is left unassigned and will be handled by the Triage Manager on-shift. + The ticket reporter should flag the issue as Urgent if the issue has the potential to result in appreciable loss of efficiency of on-sky observations, or could result in a loss of on-sky observing time. + The Triage Manager is responsible for the initial assessment of the ticket in this state and for transitioning it out of the Reported state. + From this state, the ticket can either be transitioned to ``To Do``, ``Duplicate``, or ``Cancelled``. + + - *Transition to* ``To Do``: After review, the Triage Manager should identify and assign the ticket to an appropriate assignee and communicate to them that the ticket has been assigned. + This communication should include an assessment of the urgency of the work to be done. + Once the ticket has been re-assigned and the new assignee contacted, it can be transitioned to the ``To Do`` state by the Triage Manager. + The triage manager can also add or remove the Urgent flag if appropriate. + + +- ``To Do``: The ticket has been assigned and an assessment of the work to be done is made by the initial assignee. + Work has been deemed necessary by the Triage Manager and it is the responsibility of the initial assignee to determine the scope of work and a plan to address the issue. + The ticket remains in this state until resources have been allocated and work is initiated. + + At this stage, if the initial assignee determines they are unable to complete the work, they must perform the following: + + - Find the appropriate assignee. + If they are unable to do so, then the assignee should be the current Triage Manager. + - Verify that the new assignee is able to work on the ticket + - Post a comment on the ticket indicating the reason for the re-assignment. + + - *Transition to* ``In Progress``: After initial assignee assessment and once a work plan has been identified and resources allocated to perform the work, the ticket should be transitioned to ``In Progress``. + The assignee performs the state change when work starts. + + - *Transition to* ``Transferred``: After initial assignee assessment if the work is not considered Urgent and the issue resolution will have significant impact beyond summit operations the work can proceed in a different Jira project. + Prior to transitioning the issue to ``Transferred``, the assignee must open a new ticket in the new project and the OBS ticket must be linked to the ticket in the new project. + The assignee should leave a short justification in the ticket as to why the work is being transitioned. + +- ``In Progress``: This state is reserved for tickets which are actively being worked on but may not have had a cause or solution fully identified or implemented. + The transitions from this state are dependent upon if a fix can be identified. + + - *Transition to* ``Tracking``: If the root cause and or solution to the issue cannot be identified with the information provided, it can be transitioned to ``Tracking`` while the initial assignee awaits more occurrences or information. + + - *Transition to* ``Done``: If the work needed to implement a solution can be rapidly completed, it can transition directly to ``Done``. + This transition is reserved for minor issues requiring no testing/tracking or urgent tickets requiring rapid response. + + - *Transition to* ``Testing``: Work has been done to address the issue and a potential fix has been identified and implemented. + If the fix is deployed and additional data must be collected before deeming success, it can be transitioned to Testing. + +- ``Tracking``: This state is reserved for issues which have been considered by the assignee and deemed to have insufficient information to determine the root cause or implement a solution. + If a particular data collection procedure must be followed it must be detailed in the comments section and either the Triage Manger or Run Manager should be informed so that the procedure can be communicated to the relevant stakeholders, specifically the night crews. + + - *Transition to* ``In Progress``: Once sufficient information has been collected, the ticket can be transitioned back to ``In Progress`` and the workflow proceeds as usual. + +- ``Testing``: This state is reserved for issues which have a potential fix already deployed and which are being monitored for completeness. + Data collection on the efficacy of the fix should happen in this state. + If not obvious, assignees should state what the success criteria is in a comment to transition the ticket to ``Done``. + + - *Transition to* ``In Progress``: If the fix that was deployed is deemed insufficient (e.g. recurrence of a failure is observed), it should be transitioned back to ``In Progress`` and until a new solution can be considered. + + - *Transition to* ``Transferred``: This transition is for when the work is not considered urgent and during testing it is determined that the issue resolution will have significant impact beyond summit operations the work can proceed in a different JIRA project. + Prior to transitioning the issue to ``Transferred``, the assignee must open a new ticket in the new project and link it to the OBS ticket. + The assignee must leave a short justification in the ticket as to why the work should be transitioned. + + - *Transition to* ``Done``: If the fix that was deployed is considered successful, upon completion of the work it can be transitioned directly to Done. + A short description of the final issue resolution should be included in the comments section of the ticket before transitioning to ``Done``. + +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|. diff --git a/Daytime-Nighttime-Interactions/observing-task-workflow.rst b/Daytime-Nighttime-Interactions/observing-task-workflow.rst deleted file mode 100644 index c46c14f7..00000000 --- a/Daytime-Nighttime-Interactions/observing-task-workflow.rst +++ /dev/null @@ -1,86 +0,0 @@ -.. 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 `. -.. An error will alert you of identical labels during the build process. - -.. _Daytime-Nighttime-Interactions-block-observing-workflow: - -############################### -Observing Task Request Workflow -############################### - -This page describes the overall workflow for how Observing Task requests can be submitted, executed, and completed. -It is intended to be a reference for how the various JIRA workflows (SITCOM, BLOCK, SUMMIT) can all be used together to create an effective workflow for efficiently collecting and analyzing data collected at the Rubin Observatory. -Here we define an "observing task" as any test or task that requires data to be collected at the summit using any of the observing facilities outside of normal survey operations. -This could include e.g. an engineering request or scientific dataset needed to verify a requirement or functionality. -Observing tasks can be designed to take place during the daytime (e.g. calibrations or closed-dome movements) or during the night. - -How to submit a new Observing Task Request -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Proposers for new Observing Tasks should start by submitting a SITCOM ticket describing the motivation for the task, its constraints, and specific data required. -The ticket should be given the label "observing_task" so that it may be reviewed by the Rubin Commissioning Time Allocation Committee. -If the task is part of a larger campaign, it is appropriate to provide links to a Confluence page or other external reference describing the motivation. - -Rubin Commissioning Time Allocation Committee -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The newly proposed task should be brought to the Rubin Commissioning Time Allocation Committee (RTAC) for consideration. -The RTAC is responsible for determining if the task merits execution and what priority it should be assigned for the upcoming observing test cycles. -The RTAC is also responsbile for assigning the task to a member of the Science Comissioning team for execution. - -Role of the SITCOM JIRA ticket -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The SITCOM JIRA ticket should serve as both the task proposal and central location for all efforts related to the data collection and analysis. -This could include: - - a linked BLOCK ticket describing the observing task data collection - - links to any additional pre-requisite or follow-up work such as a DM ticket to adjust parameters - - links to task analysis results such as plots, parameters determined, notebooks, or technotes -The SITCOM JIRA ticket should be assigned to the task proposer or person responsible for confirming when the task has been completed. - -Role of the BLOCK JIRA ticket -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The BLOCK JIRA project contains the tickets which describe the actions or instructions needed to collect the requested data. -These description of a BLOCK ticket should include one of the following: - - a set of scripts to be run via the script queue and their corresponding configurations - - a notebook to be run from the summit (should be added to the ticket as an attachment) - - a Scheduler-driven survey to be executed with the appropriate scheduler configuration - - a BLOCK-ID to be executed as an observation block via the scheduler - -In general, the BLOCK tickets are expected to be assigned to and followed-up by a member of the Commissioning Science team. -They should include all of the necessary instructions to run the test through completion, including and pre-requisites or limiting conditions. -The BLOCK tickets themselves will then be included in the Plan of the Night to be executed by a member of the observing team. -A single observing task defined by a SITCOM JIRA ticket may be broken up into many different BLOCKs to ease execution. - -Role of the SUMMIT JIRA ticket -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Some observing task requests (particularly those that include daytime data collection) require careful planning and coordination with summit activities. -In these cases, a SUMMIT JIRA ticket should be made and linked to the SITCOM JIRA ticket so that the task can be added to the SUMMIT JIRA calendar. - -Why do we need multiple tickets to represent a single request? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The main reasons are the difference in timescales for between data collection and data analysis, -and the need for clear, concise instructions for data collection on the summit. -Data collection and data analysis can often (though should not always) proceed in parallel, benefitting from separate workflows. -In addition, efficient execution of data collection on the summit requires modular scheduling of short tasks with concise instructions. - -Contact Personnel -^^^^^^^^^^^^^^^^^ - -This procedure was last modified |today|. - -This procedure was written by |author|. The following are contributors: |contributors|.