search

lzim / teampsd

Team PSD is using GitHub, R and RMarkdown as part of our free and open science workflow.
GNU General Public License v3.0
9 stars 23 forks source link

9/3 Revised GH Issue Template Proposal #478

Closed staceypark closed 5 years ago

staceypark commented 5 years ago

We can change what the title box prompt text says. Current: Edit the details to create a report that will help us improve. Proposal: Add deadline & descriptive detail of issue, including module or session # as relevant.

-- (Answer questions below by adding an "x" in between applicable brackets [x])

  1. Is this issue a problem/error or a new idea?

    • [ ] Problem
    • [ ] New idea

  2. In the space provided below, either 1) describe the problem you encountered or 2) describe your new idea. Provide a screenshot if possible. << Paste screenshots here>>

  3. Within which product did you notice the problem? Check all that apply

Data UI

Documentation & Resources

Sim UI Module

  1. What kind of device are you using?

    • [ ] Tablet
    • [ ] Smartphone
    • [ ] PC

  2. What browser were you using?

    • [ ] Chrome What version?
    • [ ] Edge What version?
    • [ ] Safari What version?
    • [ ] Internet explorer What version?
    • [ ] Other <>

Finally before hitting submit, make sure to:

  1. Add descriptive title & needed deadline at the top
  2. On the right hand side, under "Assignee", add all team members relevant to the issue.
  3. On the right hand side, under "Projects", assign issue to "issue_tracker"

THANK YOU!!

STOP HERE. INFORMATION BELOW IS TO BE FILLED OUT BY WORKGROUPS AS PART OF TRIAGE AND WORK BREAKDOWN PROCESS

Executive Summary

Estimated person-hours to complete:

Estimated date for completion:

Lead team for effort:

Key people (use @ assignment for people whose input will be necessary):

Step 1 - Complete the Interdependencies Table

Workgroup Leads review information provided by originator and collaborate to identify interdependencies. Then they describe modifications that are needed in the appropriate column and estimate hours needed to make changes:

● Workgroup Products - This column identifies the workgroups and the products for which they are responsible. This column can be modified by a workgroup lead on an ad-hoc basis to add one-time products or can be modified to include new and enduring products.

● Dependency? - This column is used by the workgroup leads during collaboration to identify the existence of an interdependency.

● Description of Change or Action Needed - Workgroup leads briefly describe the change required.

● Hours - Workgroup leads estimate the person-hours required to complete the task.

Workgroup Products Dependency? Description of Change Needed Hours Estimate

Documentation
Brochures | | | MTL See Guide | | | MTL Say Guide | | | MTL Videos | | | Post Test | | | Investigators | | | Presentation | | | Quarterly Report | | | Annual Report | | | Qualitative | | | MTL Fidelity Checklists | | | Systems Thinking Codebook | | | CFIR Codebooks | | | Quantitative | | | Data UI | | | Data Queries | | | SharePoint | | | Excel Outputs | | | ModelParameters | | | tt Reports | | | Model CC | | | MM | | | PSY | | | AGG | | | SP | | | Sim User Interface | | | Model Diagram | | | "i"Information | | | Experiments | | | Outputs/Charts | | | Exports | | | Master Crosswalk Table | | |

Step 2 - Identify Constraints that may affect the team’s ability to complete the necessary actions.

Describe the constraint in terms of capability, capacity or affect on grant research goals. If there are no constraints identified, then leave the table blank.

● Type - The type of constraint identifies one or more resource areas that are affected.

● Workgroup - this is the workgroup responsible for developing a new or modifying an existing product.

● Discussion/recommendation - A brief narrative that expands the information regardingthe constraint and ideally a recommendation for overcoming the constraint.

Type Constraint (check all that apply) / Workgroup(s) Affected / Discussion/Recommendation

Step 3 - Identify supported milestones. Affix the milestone at the issue level using available GitHub milestones.

Step 4 - Indicate the due date for completing the actions identified above, assuming constraints are removed.

Step 5 - Identify the lead workgroup for the action (check one):

Step 6 - Go to the top of this section and complete Executive Summary information

Note to Workgroups: Use the issue thread to document further discussion, alternatives development and estimates. However, be sure to update this form if dates, team responsibility or other information changes.

jamesmrollins commented 5 years ago

@staceypark This looks good! Thank you.

I have one suggestion - that we add instructions for making a title.

As is: Add descriptive title & needed deadline at the top

Consider: Add a title at the top in the following format: Module: Short description: deadline. (exg., AGG: missing feedback loop: 12 Aug)

jessfroe commented 5 years ago

One suggestion I have that would greatly shorten the issue template would be to remove all sub-headers both within #3 "Within which product did you notice the problem?" and the Interdependencies Table. My thought is that originators and additional team members would be able to identify specifics without the list prompt.

jessfroe commented 5 years ago

Sorry! Accidentally closed the issue.

staceypark commented 5 years ago

@branscombj @saveth @dlounsbu @holbrooa @lzim @TomRust please weigh in before end of day 8/14

saveth commented 5 years ago

Like @jamesmrollins, I do think the first line should be to instruct them to change the title of the issue. If people are going fast, they won't read the rest of the the template after the 2nd or 3rd instruction.

If we're really thinking of shortening the template, then remove the bottom section that says "STOP HERE" and put the burden on workgroup to copy that part of the template into the response.

Otherwise, the template looks good.

jessfroe commented 5 years ago

@saveth I do like that idea, of removing the bottom section. Workgroups could pull in relevant information from that piece of the template. I don't think they would need to copy and paste the whole part of the template, though. That doesn't really eliminate the length of the issue in general, just moves this to another comment/response.

staceypark commented 5 years ago

@saveth @jessfroe I agree with the frustration that the dependency table makes this issue very long. However, I don't want to ignore the purpose of the table, which I believe @jamesmrollins created to make sure all dependencies were thought of.

FYI: @lzim @dlounsbu @branscombj @TomRust @holbrooa

Proposal: Let's use labels to identify dependencies (and not what the issue is about). For example, it's redundant to tag an issue about the data UI with the labels "data_ui" or "quant". I think it's much more useful to tag "model_params" instead.

Below is the list of proposed labels. I synthesized the dependency table and the new list I proposed on #477. This should eliminate the need for the work breakdown table. It will also allow users to filter by dependency in the kanban and quickly highlight dependencies in the overall kanban view.

  1. dev
  2. doc_describe (encompasses SEE guides)
  3. doc_detail (encompasses SAY guides)
  4. doc_document
  5. doc_disseminate
  6. doc_depend
  7. fac
  8. grants
  9. hq
  10. model
  11. pi (to alert @lzim that PI action is necessary; potential to replace PIR)
  12. pubs
  13. qual
  14. quant
  15. sim_ui
  16. urgent
  17. videos
  18. wl (workgroup leads)
  19. model_section
  20. i_info
  21. exp_section
  22. outputs_section
  23. sim_export
  24. master_crosswalk
  25. tt_report
  26. model_params
  27. sharepoint
  28. data_ui
  29. fidelity_checklist
  30. progress_report
  31. cheatsheets
staceypark commented 5 years ago

newest template proposal Title box prompt proposal: Add title here in the following format: Deadline + Product: Short description (ex. 8/12 AGG: Missing feedback loop) incorporated @jamesmrollins suggestion

  1. If this is a problem: under "Projects" assign to "issue_tracker" If this is a new idea: under "Projects" assign to "feature_tracker"
  2. On the right hand side, under "Assignee", add all team members relevant to the issue.
  3. On the right hand side, under "Labels", tag all potential dependencies to the issue.
  4. In the space provided below, either 1) describe the problem you encountered or 2) describe your new idea. Provide as many screenshots as possible. << Paste screenshots here>>

Changes:

  1. People will know to identify which products were affected. We do not need to clog up a quarter of the issue real estate space with this.
  2. I propose we nix milestones (Step 3 in bottom half of issue template) for now. They add no informational or workflow value as of now.
  3. I propose we take out Steps 2-6 from the template and make it part of the SOP as:
    • Everyone WL or otherwise will always add additional members to the issue as input becomes necessary. WL will specifically have responsibility of double checking that all relevant folks have been identified.
    • If the issue assignee cannot respond to the issue needs by the identified due date, they will explain constraints, identify cost & time estimates, and propose a new due date.

      Step 2 - Identify Constraints that may affect the team’s ability to complete the necessary actions. Step 4 - Indicate the due date for completing the actions identified above, assuming constraints are removed. Step 5 - Identify the lead workgroup for the action (check one): Step 6 - Go to the top of this section and complete Executive Summary information

      • Estimated person-hours to complete:
      • Estimated date for completion:
      • Lead team for effort:
      • Key people (use @ assignment for people whose input will be necessary):
jessfroe commented 5 years ago

@staceypark Definitely on board with the idea of using labels to communicate what the table was originally meant to. I do wonder if we need labels for all 5 levels of documentation, or if those are covered elsewhere? Or if they could be more clear? I wonder if all team members will intuitively know what each of the 5 levels correspond with. I know I still don't have a great understanding of what each level refers to.

staceypark commented 5 years ago

@jessfroe on the issue of tracking documentation and following up from our discussion this morning that folks need help visualizing and tracking the documentation needs, what if... we added the 5 levels of documentation as columns in the kanban?

thoughts? @lzim @holbrooa @saveth @jamesmrollins @branscombj @dlounsbu @TomRust

jessfroe commented 5 years ago

@staceypark hmm.. I think my concern with that would be "glazing over" of the kanban categories, sort of our concern with the dependencies table. Wouldn't adding the "documentation" label, along with a partner label such as fac or see/say or qual sort of help address the specific documentation need?

staceypark commented 5 years ago

@jessfroe I don't think the issue is about being able to indicate whether or not there is a documentation need for an issue so much as having a clear, consistent workflow for anyone to track the potential documentation needs for different changes and prioritizing them against our other issues.

staceypark commented 5 years ago
  1. @staceypark will update labels table with definition and use for WL to weigh in on.
  2. @lzim wants to use milestones more.
  3. @jamesmrollins WL still need a process for triage and prioritization. We will still keep assigning all issues and bugs to the "issue_tracker" and @staceypark will update the Issue Template
lzim commented 5 years ago

@staceypark @jessfroe @jamesmrollins @branscombj @saveth @holbrooa @dlounsbu @TomRust

  1. Stacey will produce a definition for each label, so that they can be considered.
  2. SOP includes opening an issue -> goes to issue_tracker then it is dispositioned by the workgroups.
    • Current: Feature or Bug; Priority; Dependency; Estimate. (James proposes we can this workflow and Lindsey concurs)
  3. Lindsey proposes that use of milestones will help us keep track of progress to key milestones, more akin to a GANTT chart.
staceypark commented 5 years ago

@jamesmrollins @branscombj @dlounsbu @saveth @holbrooa @TomRust @jessfroe

FYI: @lzim and I reviewed this together and this is our recommendation for a short issue template that frontloads critical information at the top, but retains the existing guidance of the SOP.

issue_template Title: Deadline + Product: Short description (ex. 8/12 AGG: Missing feedback loop)

1. Add description:

<< Paste screenshots here>>

2. Click on the right: a. Projects - assign to issue_tracker. b. Assignee - assign relevant team members. c. Labels- review and select all potential MTL dependencies. d. Milestones - select the dependent milestone.

Workgroups leads Identify Constraints (check all that apply):

Add estimated person-hours to complete:

Edit the due date (if necessary)

lzim commented 5 years ago

@jamesmrollins @branscombj @dlounsbu @saveth @holbrooa @TomRust @jessfroe

I concur with @staceypark that the much shorter issue template (now implemented) is designed to retain the existing SOP with a shorter template. For example, we will retain the assignment to the issue_tracker for the purposes of triaging and prioritizing issues by the workgroup leads into the issue_tracker and feature_tracker kanbans.

Next steps:

  1. @staceypark will provide the definitions for each label - She proposes that the labels will be used as a dependency check and should be added by the person who opens the issue. Workgroup leads can also assign labels, milestones and assignees.

  2. For the next 12 weeks we will emphasize milestone r01_iir_launch and adding issues to this milestone will help us assess our progress toward this milestone - this is particularly key with documentation.

  3. Make any final edits to SOP and include the new document_tracker and manuscript_tracker and then begin using it for training.

    • Documents and manuscripts "cards" will NOT go through the issue_tracker and feature_tracker. The document_tracker and manuscript_tracker "cards" have their own SOP for tracking progress (e.g., HQ is currently populating these cards for existing tasks underway).

4. Upcoming training topics for the larger TeamPSD: a. Creating an issue for the issue_tracker and feature_tracker b. Using labels on GitHub c. Using the document_tracker and manuscript_tracker d. Filtering issues on GitHub (for yourself, open/closed, labels) e. Creating a branch f. Opening a pull request and requesting a review g. Reviewing and closing a pull request to close an issue

jessfroe commented 5 years ago

@staceypark @lzim looks good to me! Who will be responsible for updating the SOP? Should I help with that or is Stacey taking the lead?

Sent with GitHawk

lzim commented 5 years ago

@jessfroe I’m sure @staceypark and @jamesmrollins would benefit from your help with the SOP edits to stay consistent with the proposed workflow, but simplify description and add the two new trackers.

Also, we want to add the r01_iir_launch milestone to every document_tracker card. We need to power through each card in 12 weeks!

Thanks!

staceypark commented 5 years ago
  1. dev - used as an alert from James to Hiren that issues are ready to be worked on by dev
  2. document - expresses a dependency for at least 1 of 5 levels (describe, detail, document, disseminate, depend) of documentation to be tracked on the document_tracker
  3. facilitate - expresses a dependency on the facilitate workgroup
  4. grants - expresses a dependency on the grants workgroup
  5. hq - expresses a dependency on the hq workgroup
  6. model - expresses a dependency on the model workgroup
  7. pi - used as an alert to PI that an action or decision is necessary
  8. manuscript - expresses a dependency on manuscripts to be tracked on the manuscript_tracker
  9. qual - expresses a dependency on the qual workgroup
  10. quant - expresses a dependency on the quant workgroup
  11. sim_ui - expresses a dependency on the sim_ui workgroup
  12. urgent - indicates a short amount of time is available for resolution and needs to be prioritized
  13. model_section - expresses a dependency on model section of the sim ui
  14. i_info - expresses a dependency on "i" information of the sim ui, model parameters, & master crosswalk table
  15. exp_section - expresses a dependency on the experiments section in the sim ui
  16. outputs_section - expresses a dependency on the outputs section of the sim ui
  17. sim_export - expresses a dependency on the export function of the sim ui
  18. master_crosswalk - expresses a dependency on the master crosswalk
  19. tt_report - expresses a dependency on tt reports
  20. model_params - expresses a dependency on model parameters
  21. sharepoint - expresses a dependency on the sharepoint site & splashpages
  22. data_ui - expresses a dependency on the data ui
  23. progress_report - expresses a dependency on progress reports
lzim commented 5 years ago

Thanks for your work on this @staceypark

I know this is an attempt to replace the dependency table with using the color-coded, filterable, labels, and to use the list of labels as a “dependency check” to make sure we identify all MTL resources and TeamPSD workgroups that could be impacted.

At the same time...

I find 1. dev - used as an alert from James to Hiren that issues are ready to be worked on by dev and 7. pi - used as an alert to PI that an action or decision is necessary

to be the clearest definitions because they state who it is meant to alert (a point person) and what the next step or action is.

All the labels that simply state “expresses a dependency” would be more useful if they did the same thing, stating who is supposed to be alerted by or tracking that label and what is the next step.

For example, if a team member uses document then who is supposed to make sure it the issue/feature is tracked in the document_tracker when it gets to testing? That sort of thing.

Does that make sense?

FYI Workgroup Leads & HQ: @jamesmrollins @jessfroe @branscombj @dlounsbu @tomrust @holbrooa @saveth

staceypark commented 5 years ago

Is this clearer?

  1. dev - alert from James to Hiren that issues are ready to be worked on by dev
  2. document - expresses a dependency for at least 1 of 5 levels (describe, detail, document, disseminate, depend) of documentation to be tracked on the document_tracker. The point person for each level of documentation will be responsible for checking the issue & feature tracker for dependencies (describe: Jane & Debbie; detail: Tom & Lindsey; document: Stacey & HQ; disseminate: Lindsey, Andrew & Savet; depend: Lindsey, Jane, & Jessilyn)
  3. facilitate - alert all of the facilitate workgroup to an issue that may affect facilitation (Lindsey, Jane, Debbie, Tom, David, Claire, Gayle, John, Matt, Jay, Theresa, Marcia)
  4. grants - expresses a dependency that all the co-I's will need to be alerted to at the monthly co-I meeting
  5. hq - alert to HQ workgroup (Lindsey, Stacey, & Jessilyn) to track
  6. model - alert to Tom of a dependency on the model workgroup
  7. pi -alert to PI/Lindsey that an action or decision is necessary
  8. manuscript - expresses a dependency on manuscripts to be tracked on the manuscript_tracker
  9. qual - alert to David, Kathryn, Swap, Lindsey, Jessilyn, & Stacey to of dependency on the qual workgroup
  10. quant - alert to Savet & Andrew of dependency on the quant workgroup
  11. sim_ui - alert to sim_ui workgroup lead of an issue or dependency that affects the sim_ui. The workgroup lead will evaluate sim_ui impacts and collaborate with other workgroup leads to determine an adequate resolution.
  12. urgent - indicates a short amount of time is available for resolution and needs to be prioritized by workgroup
  13. model_section - alert to James of dependency on model section of the sim ui
  14. i_info - expresses a dependency on "i" information that could affect the sim ui (James & Jane), model parameters (Andrew & Savet), & master crosswalk table (James, Tom, & Andrew)
  15. exp_section - alert to James of dependency on the experiments section of the sim ui
  16. outputs_section - alert to James of dependency on the outputs section of the sim ui
  17. sim_export - alert to James of dependency on the export function of the sim ui
  18. master_crosswalk - alert to James, Tom, & Andrew of dependency on the master crosswalk
  19. tt_report - alert to Savet & Stacey of dependency on tt reports
  20. model_params - alert to Andrew & Savet of dependency on model parameters
  21. sharepoint - alert to Andrew of dependency on the sharepoint site & splashpages
  22. data_ui - alert to Andrew of dependency on the data ui
  23. progress_report - alert to Lindsey of dependency on progress reports
jessfroe commented 5 years ago

@staceypark can I edit your comment so that the labels are bold?

staceypark commented 5 years ago

@jamesmrollins thanks for updating label definitions & actions for your workgroup's labels like we decided at the last Support Workgroup Thurs meeting.

@TomRust @dlounsbu @branscombj @saveth @dlounsbu @lzim @jessfroe Please review the above list of labels used as dependency checks and their corresponding definitions for the below criteria by COB Fri, so we can review & assign definitions during the Mon Workgroup leads meeting:

  1. Identify if there are any missing labels
  2. Detail next steps by the workgroup/workgroup leads that occur when the label is used.
staceypark commented 5 years ago

@TomRust @dlounsbu @branscombj @saveth @dlounsbu @lzim @jessfroe Please update or confirm above list & definitions before our 2pm Pacific / 5pm Eastern Workflow Update meeting. If there are no further comments after that, I will just roll with the above and update the labels to say so.

lzim commented 5 years ago

@staceypark I am okay proceeding, you’ve waited long enough for people to weigh in.

We can refine if we find what you have now needs any ore action steps or point people specified