Tickets/dm 40173 #90
Tickets/dm 40173 #90
Conversation
There was a problem hiding this comment.
This is really good! I am leaving some inline comments for you to consider.
Also, I wonder what changes if we adopt the Test Cases.
I am actually good to approve the PR but I think @dsanmartim wanted to review it too.
Observatory-Control-System/BLOCKS/_static/BLOCK_Jira_workflow.png
Outdated
Show resolved
Hide resolved
| =============================== | ||
|
|
||
| BLOCK tickets are heavily relied on during both the task planning and task execution phases, | ||
| and provide a central point of communication between stakeholders and the summit crew. |
There was a problem hiding this comment.
I think this should not be a line break.
| **Assignee** | ||
| ^^^^^^^^^^^^ | ||
| The Assignee is the member of the Commissioning Science team expected to oversee the task during the preparation and execution phase. | ||
| They are expected to collaborate with the Proposer during task preparation, and are directly responsible for ensuring the task is Ready for execution at the summit. |
There was a problem hiding this comment.
I think these two phrases could be in an itemized list. They are important and having them as bullet points help with visibility.
There was a problem hiding this comment.
Good point. David provided an example formatting below that I will adopt for both Assignee and Proposer sections.
| Here we provide a bulleted list illustrating an example workflow. | ||
|
|
||
| * Stakeholder requires an observing task to be completed at the summit, and describes the task in an LVV ticket, SITCOM ticket, or Confluence page. | ||
| * Stakeholder proposes a new BLOCK Jira ticket, providing links to supporting material and assuming responsibility of Proposer. |
There was a problem hiding this comment.
I think it might be worth explaining that the Stakeholder that "requires an observing task" is not necessarily required to author the BLOCK ticket. I think in a significant number of cases, these will be different people.
| * Description, high-level overview of test | ||
| * Pre-conditions/requirements to run test, including system status | ||
| * Environmental Constraints on test (e.g. observing conditions/time) | ||
| * Test Execution Instructions |
There was a problem hiding this comment.
Should we move this and the next items to the Test Case instead? we don't want to duplicate information right?
There was a problem hiding this comment.
But who will create the test case? Some people may not be familiar with the test cases in Zephyr. So, duplication might be welcome, since a ComSci will need to transfer that information to the test case. Unless ComSci gets that information directly from proposer and put it in the test case
There was a problem hiding this comment.
See my comment below.
| * Photometric conditions required. | ||
| * Test must be executed between 12:00 and 01:00 local time. | ||
|
|
||
| **Test Execution Instructions** |
There was a problem hiding this comment.
Same as above, should we change this based on the adoption of Test Cases?
There was a problem hiding this comment.
See my comment below.
| For example, if a JSON BLOCK has been prepared to execute the test, this should be something like: | ||
| * Run the JSON BLOCK using the add_block.py SAL Script with the following configuration - id: BLOCK-123 | ||
|
|
||
| If the test execution involves a series of SAL Scripts, provide the script names and all required configurations. |
There was a problem hiding this comment.
See my comment below.
| BLOCK Ticket Requirements | ||
| ========================= | ||
|
|
||
| In addition to the standard JIRA ticket fields, proposers are also required to supply the following information: |
There was a problem hiding this comment.
You need to add a line break here to render the bullets.
| The Proposer is the stakeholder requesting the observing task. | ||
| They are chiefly responsible for the initial ticket submission, including providing links to supporting materials, and the final ticket sign-off (see Transitioning to Done). | ||
| They are expected to work closely with the Assignee during the Preparation phase, but are not expected to be involved in planning when a task will take place or during the task execution (unless otherwise required). | ||
| Anyone can take the role of Proposer as long as they are knowledgeable in the task requirements and completion criteria. |
There was a problem hiding this comment.
In line with Tiago's comment, I think this also should be given in bullets. I've expanded it a little to include a couple of extra information. Below, I copied what I did for the "proposer" and "assignee" responsibilities. Feel free to use (or not use) it:
Proposer
--------
The Proposer is typically a stakeholder interested in the observing task's outcomes.
Key responsibilities include:
- **Initial Ticket Submission**:
- They are chiefly responsible for the initial ticket submission, providing a detailed description of the observing task.
- Includes necessary supporting materials, such as links to relevant tickets (e.g., SITCOM, LVV) or documentation on Confluence pages.
- **Collaboration during Preparation**:
- Collaborates with the Assignee during the Preparation phase to ensure all task requirements and completion criteria are clearly understood.
- **Final Verification and Sign-Off**:
- Review the outcomes after task execution to ensure objectives have been met.
- Verifies and confirms task completion, reviewing any related data or results.
- Transitions the ticket to "Done" to officially close the issue once satisfied with the task completion.
.. note::
Anyone can take the role of Proposer as long as they are knowledgeable in the task requirements and completion criteria.
Assignee
--------
The Assignee is a member of the Commissioning Science team, responsible for overseeing the task from preparation through execution.
Responsibilities include:
- **Task Preparation and Planning**:
- Collaborates with the Proposer to understand task requirements during early preparation stages.
- Prepares the task for execution, including finalizing methodological details and setting up necessary components.
- **Marking as Ready**:
- Marks the ticket as "Ready" once all preparations are complete and validated, indicating it is prepared for execution.
- **Advocacy and Tracking**:
- Advocates for the task in planning meetings to ensure it is prioritized and scheduled.
- Tracks the task’s progress through to execution, addressing any issues that may arise.
- **Role during Execution**:
- Ensures everything is in place for successful execution, although the actual execution is typically done by an Observing Specialist.
There was a problem hiding this comment.
Thanks, I like this format. I will adopt.
| * Stakeholder proposes a new BLOCK Jira ticket, providing links to supporting material and assuming responsibility of Proposer. | ||
| * New BLOCK Jira ticket is reviewed by Commissioning Science team during one of the regular, weekly planning meetings, and accepted/rejected for scheduling. | ||
| * New BLOCK Jira ticket is given a priority for scheduling and a Commissioning Scientist is Assigned the ticket, taking on the responsibility of Assignee. | ||
| * Proposer and Assignee work together to prepare BLOCK ticket for execution. |
There was a problem hiding this comment.
Maybe you can include one extra step to tell that before marking as Ready there will be a validation phase done by a Com Sci.
| * Description, high-level overview of test | ||
| * Pre-conditions/requirements to run test, including system status | ||
| * Environmental Constraints on test (e.g. observing conditions/time) | ||
| * Test Execution Instructions |
There was a problem hiding this comment.
But who will create the test case? Some people may not be familiar with the test cases in Zephyr. So, duplication might be welcome, since a ComSci will need to transfer that information to the test case. Unless ComSci gets that information directly from proposer and put it in the test case
| 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. | ||
|
|
||
|
|
There was a problem hiding this comment.
Here we could add one more section providing a kind of a "checklist" for both roles, to make sure they do not forget anything. I prepared something, in case you think it is valuable (feel free to reject it, of course):
BLOCK Ticket Lifecycle Responsibilities Checklist
=================================================
Proposer Checklist
------------------
Initial Ticket Submission
^^^^^^^^^^^^^^^^^^^^^^^^^
- Identify the need for an observing task.
- Draft a clear description of the observing task, including high-level objectives and specific requirements.
- Gather and attach supporting materials such as relevant tickets (SITCOM, LVV) or documentation on Confluence pages.
- Create and submit the BLOCK Jira ticket.
- Provide an original time estimation for the task execution, including preparation and any additional time for configuration or logging.
Collaboration during Preparation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Review and discuss the preparation details with the Assignee to ensure all task requirements are clearly understood.
- Provide any additional information or clarifications needed by the Assignee.
Final Verification and Sign-Off
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Review the outcomes of the executed task to ensure all objectives have been met.
- Verify the completeness and accuracy of the data or results collected.
- Provide final sign-off and transition the ticket to "Done" if satisfied with the task completion.
- Initiate reevaluation if the task outcomes do not meet the expected criteria, by transitioning the ticket back to "Proposed."
Assignee Checklist
------------------
Task Preparation and Planning
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Receive and review the BLOCK ticket once assigned by the Commissioning Science team.
- Collaborate with the Proposer to fully understand the task requirements and expectations.
- Plan the detailed preparation of the task, including method selection (e.g., JSON BLOCK, SAL Script) and setup.
- Prepare and configure all necessary components or settings for the task.
Marking as Ready
^^^^^^^^^^^^^^^^
- Conduct a thorough final check to ensure all preparations meet the required standards and are fully operational.
- Validate all configurations and preconditions for the task execution.
- Mark the BLOCK ticket as "Ready" indicating readiness for execution.
Advocacy and Tracking
^^^^^^^^^^^^^^^^^^^^
- Advocate for the task in planning meetings to ensure it is scheduled based on its priority.
- Track the status of the task and update its priority if necessary.
- Ensure the task is added to the execution plan and adequately prepared for execution at the summit.
Role during Execution
^^^^^^^^^^^^^^^^^^^^^
- Provide necessary instructions or clarifications to the Observing Specialist or execution team at the summit.
- Monitor the execution of the task and be available to address any issues that may arise during the execution phase.
Observing Specialist Checklist (Execution Focused)
--------------------------------------------------
- Review the task details and any specific instructions before execution.
- Execute the observing task as planned during the scheduled night.
- Report any issues or deviations during execution to the Assignee.
There was a problem hiding this comment.
I like this idea, it's kind of a different way to visualize the information that might be easier to reference. I will add it as part of my edits and we can see how it renders.
| * BLOCK ticket is executed at the summit by Observing Specialist. | ||
| * Data is analyzed by the Proposer and ticket is reported on supporting tickets (e.g. SITCOM). | ||
| * Proposer verifies observing task is completed and transitions ticket to Done to close issue. | ||
|
|
There was a problem hiding this comment.
Before starting the new section, maybe would be a good idea to add a diagram focused on the responsibilities, rather than in the ticket states. If you like this idea, here is a suggestion:
There was a problem hiding this comment.
Thanks for the suggestion. I like the checklist representation a little better than the diagram. The workflow is pretty linear, but the responsibilities go back and forth between roles depending on the state so that switching is tough to represent visually. I think I will skip adding the diagram here but keep the checklist.
|
I proposed this on slack but want to add it here for clarity; how we use the test-cases and the workflow of who/when they need to be setup is an open question we still need to answer as a comm sci group. I propose we merge the document as-is (without mention of Zephyr Scale or Test Cases) and open a new PR to edit once the process is finished. As recommended on slack, I will add a note about this in the section on BLOCK ticket requirements. |
edennihy
force-pushed
the
tickets/DM-40173
branch
2 times, most recently
from
d6916c2 to
067e0ca
Compare
edennihy
force-pushed
the
tickets/DM-40173
branch
from
067e0ca to
dde3825
Compare
No description provided.