website icon indicating copy to clipboard operation
website copied to clipboard
verified publisher icon hackforla

Update Wiki page "How to Create Issues" to include Emergent Request issues and procedures

Open roslynwythe opened this issue 2 years ago • 13 comments

Overview

As development team leads, we need to update the wiki page "How to Create Issues" to include a description of "Emergent Request" (ER) issues and the procedures around ER creation, labeling and approval.

Action Items

  • [ ] Add a new section "Emergent Requests". See the comment below for a draft of the new section content.

Resources/Instructions

Wiki: How to Create Issues.

roslynwythe avatar Jul 06 '23 08:07 roslynwythe

Hi @roslynwythe.

Please don't forget to add the proper labels to this issue. Currently, the labels for the following are missing: Complexity, Role, Feature

NOTE: Please ignore the adding proper labels comment if you do not have 'write' access to this directory.

To add a label, take a look at Github's documentation here.

Also, don't forget to remove the "missing labels" afterwards. To remove a label, the process is similar to adding a label, but you select a currently added label to remove it.

After the proper labels are added, the merge team will review the issue and add a "Ready for Prioritization" label once it is ready for prioritization.

Additional Resources:

github-actions[bot] avatar Jul 06 '23 08:07 github-actions[bot]

Emergent Requests ERs are used to document the requirement for a new issue. Often the requirement has arisen in the process of working on a previous issue or PR. The ER outlines the requirements and an approach that will be implemented in a new issue or Epic, so that the proposed solution can be discussed and approved prior to the creation of the issue. An Epic is indicated if the requirements dictate a need for multiple issues.

Writing an ER

  1. Create a New Issue using the Emergent Request template.
  2. Apply labels to the ER that are appropriate for the issues that are expected to result from the ER.
  3. Apply Complexity: see issue making label and one of the following: a. Issue Making: Level 1 - Make issues from a template and a spreadsheet b. Issue Making: Level 2 - Make an issue template an a Issue Making: Level 1 issue c. Issue Making: Level 3 - an Epic
  4. Do not self-assign the ER unless you plan to complete the process by writing the resulting issue or Epic.
  5. Complete all relevant sections of the ER template.
  6. If you wish to write the issue, continue with the steps below in "Writing an Issue from an ER"

Writing an Issue from an ER

  1. Self-assign the ER to indicate that you are taking responsibility for creating the resulting issue.
  2. In the "Proposed Solutions (draft)" section, outline a proposal for an issue or Epic to fulfill the requirement.
  3. Set the ready for merge team label. A dev lead will respond in a comment indicating request for changes, approval to move forward with issue writing, or request for approval from product managers. 3a. If you are a dev lead/ merge team member, skip to step 4 unless approval from product managers is needed.
  4. When approval is granted, create the new issue with a Draft label and self-assign it.
  5. Add a reference to the ER in the Resources section of the new issue.
  6. Add a comment in the ER referencing the new issue.
  7. When the issue is ready for approval, remove the Draft label and add merge team lead. A dev lead/merge team member will review the issue and will request approval/prioritization from product managers.
    7b. If you are a dev lead/merge team member, add `Ready for Prioritization' instead of 'ready for dev lead' or 'ready for merge team'.

When the issue is prioritized, the PM will unassign the author from the issue and close the ER.

roslynwythe avatar Jul 06 '23 08:07 roslynwythe

@hfla-site-merge If you are interested in procedures and policies around issue writing, please review the above draft and comment. Thank you

roslynwythe avatar Jul 13 '23 02:07 roslynwythe

@roslynwythe This is great and very helpful! These instructions and the process are clear and will definitely work as a system for approval of issues before they are written up. I used this process for my recent ER and it worked well. I had a few minor edits/suggestions.

  • Minor edit for a typo in the Writing an Issue from an ER section. Step 2 has a typo and says changeses instead of changes.
  • Potentially break up some of the steps into separate steps and reordering a bit to make it marginally easier to keep track of the steps (see below this list for my suggestions).
  • I am wondering if we need to add the Draft label to the ER itself in step 1 of the Writing an Issue from an ER section since the ER itself is not a draft. Will it be confusing if we are potentially adding the draft label when the ER is incomplete and also when someone is assigning themselves before creating an issue? Maybe it will be clear from context since the ER will be assigned?

Writing an Issue from an ER

  1. Self-assign the ER to indicate that you are taking responsibility for creating the resulting issue.
  2. Add the Draft label to the ER.
  3. Read the ER and post a new comment that outlines a proposal for an issue or Epic to fulfill the requirement.
  4. Set the ready for merge team label. A dev lead will respond in a comment indicating request for changes or approval to move forward with issue writing, or may request approval from product.
  5. When approval is granted, create the new issue with a Draft label and self-assign it.
  6. Add a reference to the ER in the Resources section of the new issue.
  7. Add a comment in the ER referencing the new issue.
  8. When the issue is ready for approval, remove the Draft label and add ready for merge team. When the issue is prioritized, the PM will unassign the author from the issue and close the ER.

LRenDO avatar Jul 13 '23 03:07 LRenDO

Hi @LRenDO, I think you are correct; the status of the ER should be clear from the assignee and from the other labels, so the Draft label is not necessary and I've updated the instructions accordingly. Thanks also for your suggestion to break up the steps. Your revision is a big improvement and I've updated the draft based on your steps. You are amazing!

roslynwythe avatar Jul 15 '23 00:07 roslynwythe

@roslynwythe you're amazing! You're doing so many things for HFLA! Glad it was helpful. Happy to contribute to the process!

LRenDO avatar Jul 15 '23 13:07 LRenDO

Hi @roslynwythe, great job on the instruction write up! I've added step 3a to the "writing an issue from an ER" section to clarify that dev leads/ merge team members can skip step 3 if they are writing the issue themselves since they can self approve it. I've also updated step 3 as well. Feel free to keep, update, or remove the changes as needed.

I do have a couple of questions:

  • For step 6 of the "emergent request" section, does the draft label remain on the ER if we decide to work on it even if the draft of the ER is finished?
  • For step 7 of the "writing an issue from an ER" section, is the intention to add "ready for product" instead of "ready for dev lead" since the issue will be prioritized?

Writing an Issue from an ER

  1. Self-assign the ER to indicate that you are taking responsibility for creating the resulting issue
  2. Read the ER and post a new comment that outlines a proposal for an issue or Epic to fulfill the requirement.
  3. Set the ready for dev lead label. A dev lead/ merge team member will respond in a comment indicating request for changes, approval to move forward with issue writing, or approval from product managers.
    3a. If you are a dev lead/ merge team member, skip to step 4 unless approval from product managers is needed.
  4. When approval is granted, create the new issue with a Draft label and self-assign it.
  5. Add a reference to the ER in the Resources section of the new issue.
  6. Add a comment in the ER referencing the new issue.
  7. When the issue is ready for approval, remove the Draft label and add ready for dev lead. When the issue is prioritized, the PM will unassign the author from the issue and close the ER.

Adastros avatar Jul 18 '23 06:07 Adastros

Thank you @Adastros for your excellent suggestions. I updated the draft to incorporate each of your suggestions.

Regarding your questions:

  • For step 6 of the "emergent request" section, does the draft label remain on the ER if we decide to work on it even if the draft of the ER is finished?

I removed the instruction to add Draft label to the ER while it is being prepared. Ren has suggested that the Draft label was not really necessary and I agree, although I'm open to discussion if you feel the Draft label would serve a useful purpose in this context.

  • For step 7 of the "writing an issue from an ER" section, is the intention to add "ready for product" instead of "ready for dev lead" since the issue will be prioritized?

I've revised step 7 to clarify. Please let me know if it needs work:

  1. When the issue is ready for approval, remove the Draft label and add ready for dev lead. A dev lead/merge team member will review the issue and will request approval/prioritization from product managers.
    7b. If you are a dev lead/merge team member, add `Ready for Prioritization' instead of 'ready for dev lead'.

When the issue is prioritized, the PM will unassign the author from the issue and close the ER.

roslynwythe avatar Jul 18 '23 07:07 roslynwythe

Thanks for implementing my suggestions and answering my questions @roslynwythe! The revised step 7 is a lot clearer. I have no further thoughts on the ER procedure at this time.

Adastros avatar Jul 21 '23 07:07 Adastros

@hackforla/website-pm please review draft https://github.com/hackforla/website/issues/4916#issuecomment-1623223460

roslynwythe avatar Jul 25 '23 01:07 roslynwythe

Hi @roslynwythe! I was at the issue making workshop with @Adastros tonight and I noticed it looks like we could add a couple more details to this process.

In the making the ER section:

  • In step 2, add something like "as well as an Issue Making label"

In the making an issue from the ER section:

  • In step 4 or step7, add something like "add issue to the New Issue Approval column in the project board"

LRenDO avatar Jul 25 '23 04:07 LRenDO

@roslynwythe ill look at this after all the comments have been integrated.

ExperimentsInHonesty avatar Aug 06 '23 16:08 ExperimentsInHonesty

a. Issue Making: Level 1 - Make issues from a template and a spreadsheet b. Issue Making: Level 2 - Make an issue template + Issue Making: Level 1 issue or Make a single issue c. Issue Making: Level 3 - an Epic d. Issue Making: Level 4 - Make a Rollout Plan that has >1 epics to achieve and timelines for interdependencies

after small and pr reviews (pick good first and small)

  1. Issue Making: Level 1 - Make issues from a template and a spreadsheet . after medium and pr reviews (pick first, small medium in that order)
  2. Issue Making: Level 2 - Make issue(s) from an ER or Epic

after large and pr reviews (good first, small, medium)

  1. Issue Making: Level 3 - Making a template + Create a Level 1 issue(s) + sample issue using template

after xtra large and pr reviews (medium or higher)

  1. Issue Making: Level 4 - Create an Epic Issue, and it's Level 2 or 3 issues

  2. Issue Making: Level 5 - Make a Rollout Plan that has >1 epics to achieve and timelines for interdependencies

Potential solutions summary [draft]

(Recommended that Author of ER writes this, but not required. If you are not going to write it, please add a ready for merge team label on this issue) Example: We are mis-capitalizing Slack throughout the site, the draft would say "Make a list of all instances of "slack" in the code/wiki/issue, create a rule which governs which ones to change, identify which ones need to be changed, write issues to change the instances"

Issues to Make from this ER (and their size labels)

(This gets written after the potential solution has been accepted by merge team or dev lead, or product. It is optional for Author to write, required for prioritization) Example: see

ExperimentsInHonesty avatar Jun 04 '24 17:06 ExperimentsInHonesty