-
Notifications
You must be signed in to change notification settings - Fork 0
How to create issues
Hello everyone! This guide is all about issue creation. As a member of the Hack For LA team, you need to know how to create issues for other team members. Issue creation is a valuable skill as it trains you how to communicate tasks in an effective manner and keep the team running. A team that cannot relay clear and specific tasks to one another is a team that cannot function, after all! So thank you for reading this guide!
[TODO, put a curated list of good issues to look at, organized by size]
To create your first issue, you need to locate the issue creation button! To find it just click on the issues tab, and then look for the new issue button to the right of the screen. Click on that, and you can get started!
[TODO screenshots of button to click]
At Hack For LA, we have several templates to choose from, but regardless of which one you choose, the steps are mostly similar. Read the description in each of the templates and click on the one that fits your purpose the most. If all else fails, please pick the Blank Issue Template, which can be used to fulfill any of your glorious purpose.
[TODO gif of glorious purpose template]
The Overview is the first part of any issue. It serves as a two sentence summary of what the issue is about, so that anyone reading it can get a quick sense of what the issue is about. Remember, to keep it at two sentences, because anything too long should be placed further down in the Resources/Instruction sections instead. Below is a good two sentence fill-in-the-blank that you can use if you find yourself thinking too hard about how to summarize the issue.
As a [developer/programmer/designer/member of the team/etc], we need to [insert some sort of standard, such as "keep out code clean" or "fix bugs" or "make sure website appears welcoming"]. For this issue, we will [do something to fulfill our standard, such as "edit the code in the data folder or "correct a bug in out components" or "increase the title size on the homepage"].
Action items can be thought of as a checklist of items to complete for the issue to close. This checklist is occasionally an ordered list, but often times, the checklist is organized in a way that sounds ordered, but can be completed in any order. To create action items, some find it more useful to think of them as steps, and others as an unordered list.
The trend for action items are to write them specific to the size of the issue. Issues of a smaller size tend to have clearer items, such as, "locate the line that says, "font-size: 16px", and change it to, "font-size: 12px". However, as issues grow larger, the item might instead be less clear, such as, "change the font size for all titles to 12px", or "look at the Figma file for the font size, and verify that the font size matches". Other issues, however, would not have clear steps, such as feasibility issues, where the end product is clear, but the ways to do so is a little unclear. In cases like this, we encourage you to try your best, and to look up some of our past issues [TODO add link to past issues section] to see how the were written. You can also consult more senior team members for their assistance and opinions.
When writing action items, it is also perfectly fine to just write down whatever comes to mind, and edit it later. Since all new issues go through an approval process, it does not matter if it is messy, as someone else will review it with you and clean it.
The Resources/Instruction section is there to provide information that neither fits the overview, or can be considered as part of the action items checklist. The most common information provided are links that lead to supplementary material. For example, if the issues involved changing the homepage, it would be courteous to link the actual homepage, or the file that should be changed. And just like with the action items, the amount of links provided should reflect the issue's size. As with the aforementioned homepage changes, if the issue is considered medium or large, there is no need to link the homepage as team members should know where to find it. Rather, it might help to link to outside articles or documentation that will illuminate the task. For example, if it involves changing the color palette, an article about color contrast might help the team member with the issue.
When making issues, there always need to be at minimum, 3 labels. These labels are:
- 1 from the
sizeseries [TODO link] - 1 from the
roleseries [TODO link] - 1 from the
Featureseries orP-Featureseries [TODO link]
More information about what each of these labels mean can be found by clicking the links above. Also, note that the minimum is 3 labels, by there are no maximum. Indeed, an issue can have as many labels as GitHub would allow. That does not mean labels should be placed without thought. The purpose of labels is to convey accurate information about the issue while using as little as possible. When adding a fourth label, do think about whether the label applies to this issue. For example, if an issue requires some other issue's completion before this one can begin, then the dependency label is needed. Likewise, if an issue involves a heavy amount of work that should be done as a group, then the collaborative work label is needed.
If this is your first time making issues, we do not expect you to have encyclopedic knowledge of every label we use, so try your best to use our guide about labels to add the minimum 3. If you are still stumped, then feel free to leave it alone for now, and ask questions. The team is always ready to coach you, and would love to help answer any questions you may have!
After filling out the issues and adding the labels, the last step is to add the issue to the project board. We do have automation that partially does this already, but it is always good to double check. To check, simply locate... [TODO gif]
If the issue is not already in the Project Board, then...
A dependency is a condition that must be fulfilled before work on an issue can begin. A dependency can take many forms, but it is often an issue. When adding dependencies to an issue, be sure to add a section called Dependency, and add the dependency as a checkbox. Issues with a dependency goes into the [ice box][TODO icebox link], until such a time when the issues are ready to be worked on. If the dependency is an issue, it is also customary to go to that issue and put "release the dependency" as an action item. For example, if #1911 is dependent upon the completion of #1823, then #1911 will have a Dependency section. On #1823, the last action item should be, "release dependency on #1911". This makes sure that there is ample follow up so issues do not become lost.
Yes! An issue that is not ready to be worked is referred to as, "having a dependency". To learn more about dependencies, take a look at this question.
To release a dependency means to move an issue with a dependency back into the new issue approval from the [ice box][TODO icebox link]. The dependency label should also be removed from the issue.
Click the arrow below each category to view links (or view original alphabetical list by clicking "Pages" above) :