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. Identified by the label
issue level III: epic - Main Issue - This issue is responsible for tracking the request issue for this feature. Identified by the label
issue level II: main - Request Issue - the smallest type of issue. This issue can be a standalone task or the child issue of a main issue. Identified by the label
issue level I: request
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. This allows us to separate the work and get it done quicker. 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 managing updates to multiple features.
For example, if we're adding a new feature to the about page and will need more than one team involved, we'll create a Main Issue describing the update 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 entirety of the update 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 separate request issues (i.e. Design Glossary Tool Tip, Code Glossary Tool Tip, etc).
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.
Pro tip: Check out How to Change Action Items into Child Issues
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. Err on the side of adding too much information rather than too little.
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. These will be set by Team Leads and PMs.
For any team related processes, use the Team Workflow milestone.
As of Mar 1, 2024, our primary milestone is currently Launch Prep.
It all starts here. ✨
We currently only have one, Blank Issue, which makes the decision very easy.
You can reach the issues template page here or through the green New Issues button on the Issues page.
Add any issues blocking progress on this issue.
For example if there is a request to update an image on the landing page, a design issue (choosing and providing the image) would have to happen before the dev issue can be started. Therefore if we were writing the dev issue, we'd mark the number of the design issue under dependencies.
The overview provides all the context and information that someone will need to complete the issue. This is especially important considering our teams are ever-rotating and the person completing the issue is almost definitely not the one who wrote it.
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 related to another issue?
- What extra info or specifications might be helpful?
User stories are also helpful for putting together an effective overview.
- What kind of user would want this feature?
- As a user, why is it useful?
- If it's a UX improvement, how would a user encounter that situation?
It's always better to err on the side of adding too much information, especially on a main issue. A team's lead can always pare down what isn't relevant for the team-specific request issues.
This is where a bulk of the decisions about organizing the issue will happen.
Regardless of issue type, action items are small measurable to-do items required to complete the issue.
As you fill out this section, you may notice the action items covering a certain team's domain or just large measurable chunks. A good rule of thumb is that if more than one person is required to complete an issue, it should be broken into smaller issues. When this occurs, you will want to make this a issue level II: main issue and convert the action items into issues.
This space is particularly for any assets needed to complete the issue or notes from the lead. For example as dev lead, I will add files that I think might be relevant for to complete that issue.
These are the necessary parts of an issue that exist pretty exclusively for tracking purposes.
If there is an obvious team lead you would like to assign this issue to, add them here.
If not, Leads and PMs will assign this.
If you create an issue through the new issue page on github instead of through converting an action item to an issue, the minimum required labels will populate as 'missing'. For ex, role: missing. Replace at a minimum the role and feature labels. If you are unsure about size or priority, leave for Leads and PMs to add.
In order for this issue to show up on our 'Expunge Assist Project Tracking' board and be tracked accordingly, the issue has to be manually added to the board.
After it's added, it will automatically be routed to the new issue approval column. Leave it there. This is notifies PMs and Leads there is a new issue to review and assign priority.
If you are aware of the milestone we are currently working toward, add it. Otherwise, team leads and PMs will add it.
Epic: #1135
Grey lines show the hierarchical relationship between issues. The purple lines show dependencies.