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

[roslynwythe]

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.

[github-actions[bot]]

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:

• Wiki: How to create issues
• Wiki: How to read and interpret labels

[roslynwythe]

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 dev lead 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 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]

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

[LRenDO]

@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 dev lead 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 dev lead. When the issue is prioritized, the PM will unassign the author from the issue and close the ER.

[roslynwythe]

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!

[LRenDO]

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

[Adastros]

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.

[roslynwythe]

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:

7. 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.

[Adastros]

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.

[roslynwythe]

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

[LRenDO]

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"

[ExperimentsInHonesty]

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

[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