How to Create Issues
Hey hi hello! This guide is dedicated to the Expunge Assist processes around issues. Issues are a great resource for documenting and tracking events like the status of a request, when a bug was found, or a feature was suggested.
We're reorganizing our issue process to group together related issues into parent and child issues. By breaking up the issues into either smaller actions or team requests and linking them, we are combining the knowledge surrounding that request into a single place.
- Epic Issue - a top-level issue. This type of issue should only be created by PMs and Leads for larger releases.
- Main Issue - It may or may not have children issues. This issue should cover the umbrella of the request.
- Child Issue - an issue related to a larger higher-level issue. Child Issues are action items large enough require input from multiple people or teams.
For example, if we're implementing a new feature and will need more than one team involved, we'll create a Main Issue describing the feature and listing out the action steps. These will often shake out to be major steps and cross-functional teams' tasks. The Main Task will describe what the feature is, why we're implementing it, and specifications for the request. If the feature requires help from multiple teams, their related issues will be stored as child issues (i.e. Design Glossary Tool Tip, Code Glossary Tool Tip, etc).
Epics should be used if you have several related Main Issues going on at once. For example if a similar change needs to be made to several pages, we separate the issues because changes from one page do not affect another page. However from a project management standpoint, PMs and Leads need to make sure that all the issues are completed and Epics are a reliable way to do that. TLDR; Epics are a project management tool.
Pro tip
Check out How to Change Action Items into Child Issues
Most issues will fall under this category.
- A content issue to update wording on the website.
- A development issue to add a github action.
- A design issue to update the landing page image.
This template will mostly likely need the Blank Issue template.
These issues are for bugs on the website. Did you find a weird glitch on the site? To solve a bug, we need as much information as possible to be able to recreate it. This type of issue will ask lots of questions about your internet browser(chrome, firefox, safari, etc) and your operating system. These are auto-assigned to the Dev lead to review and assign to the team.
The Overview should be a couple sentences describing the issue. This is an important space to put context for the issue, so those assigned to the issue can complete it as efficiently as possible.
Some questions to ask yourself while writing an overview:
- What specifically is the issue you're submitting? Is it a bug, a new feature, a content update? Get specific.
- Why are we doing it?
- How did this issue come up? Is it the child issue?
- What extra info or specifications might be helpful?
User stories are also helpful for putting together an effective overview.
The action items are steps to complete the issue. When starting an issue, we want to break up an issue into big steps first. This will help determine the scope of the issue. If the action items will require more than one person or team to work on them efficiently, we'll break the action items into 'Child Issues'.
This may contain notes and context about how to complete the task. If this task needs a deliverable from another team (like code needing a figma from design), it will be located here.
If an issue is blocked by another issue, that issue is given a dependency label and placed in the icebox. At the top of the blocked issue, all issues preventing any work on this issue are listed under the Dependency title.
### Dependency
- [ ] #BLOCKING_ISSUE
If listed with a checkbox, the issue will track the #BLOCKING_ISSUE and will check off and change color when that issue is completed.
When the final #BLOCKING_ISSUE is completed, the dependency label is removed and the issue is moved to New Issues waiting for approval for the Team lead to assess.
Hack for LA requires 4 labels on every issue to help sort the project board: size, priority, role, and feature. If you're ever unsure, there are 'missing' labels for each one, ie. 'size: missing'.
Size is an estimate to how much time and how complex an issue may be. We use a point system where
- 1pt - 6 hours or less
- 2pt - 7 - 12 hours
- 3pt - 13 - 18 hours
- 5pt - 19 - 30 hours
- 8pt - 31 - 48 hours
- 13+pt - main issue/must be broken into smaller issues.
You may also see 'good first issue' and 'good second issue' size labels, but these are less common.
Priority is how important an issue is relevant to the other issues. We use a simple system: low, medium, and high.
The Role label is to quickly sort the board for relevant tasks to your team. The current team labels are:
- design
- development
- research
- product management
- UX content writing
- lead
The lead label is added in addition to the other role labels to designate if that teams lead needs to do this task. For example if we had an issue updating github branch securities, it would get a role: development label and a lead label because only a lead has access to those settings in github.
A feature is a distinctive part of the app that we can reference. HfLA uses an expanded definition organizing other teams' projects into features as well.
HfLA also differentiates between features and p-features. A p-feature is a literal page or component on the app. A feature may be related to several p-features. For example the Letter Generator is more than just a page or component on the site, so it would be considered a feature, but it's made up of several pages (ex, /form/introduction. These pages are all p-features that make up a larger feature, the Letter Generator.
P-Feature examples on our app:
- Footer
- Progress Bar
- About page
- FAQ page
- Landing page
Feature examples
- Letter Generator
- Routing (the order of the pages)
- Any of the flows in the letter generator
- Design System
- UX Content Writing
When selecting or creating a feature label, ask yourself
- is this an enhancement on an existing part of the app? - look through existing labels
- is this a new addition to the app? - create a new label
Milestones are a team-agreed upon goal to which we are trying to get the project. In order to make the status of the project more clear, Team Leads and PMs collaborate to evaluate our current goals to create significant points called 'milestones'. Think of milestones like the steps required to move the project to the next stage. This is increasingly important as we get closer to MVP release. Identifying issues that fall under the current milestone helps determine priority.
It all starts here.