How to Create Issues - hackforla/expunge-assist GitHub Wiki

Introduction

This guide is dedicated to the Expunge Assist process around issues. Issues are a resource for documenting and tracking feature development, bugs found on the site, and other tasks to be completed.

Hack for LA also uses GitHub issues to log team meetings and decisions. In addition to the types of situations that issues might document above, issues and the comment history on them are also used for:

  1. Recording meeting notes: meeting notes are taken as comments to agenda issues such as this one
  2. Track administrative tasks that do not affect the codebase such as this

The information below applies to standard items that affect the Expunge Assist website.

Table of Contents

About

Types of Issues

Issues are split into different levels depending on the amount of work involved and how the team is tracking that work.

  • Epic: a top-level issue. This type of issue should only be created by PMs and Leads for larger releases, and usually include multiple Main issues as a part of it. Identified by the label issue level III: epic
  • Main: This issue is responsible for tracking multiple Request issues that make up developing a feature. Identified by the label issue level II: main
  • Request: 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

Epic Issue

Epics are a large, high-level project or feature that is too big to complete in a single work iteration, so it's broken down into smaller, manageable user stories. On Expunge Assist, Epics should be used if you have several related Main or Request issues going on at once.

For example, if a similar change needs to be made to several pages, we separate the issues because updates on one page do not affect another page. This allows us to separate the work and get it done more quickly, but also track the overall status and completion of all related issues. Epics should only be created by PMs or Leads.

Main Issue

Expunge Assist primarily uses Main issues to track feature development across teams.

For example, if the team wants to add a new section to the About page, we may need the Research team to conduct research about what to include, Content to write new copy, Design to decide how the section looks and how a user interacts with it, and Development to implement the update. One Main issue would describe what the entirety of the feature update is, why we're implementing it, and specifications for the request, and four related Request issues to cover the various teams' work would outline the specific tasks for those teams.

Request Issue

Request issues are the smallest level of issue in GitHub, and should be the smallest piece of work to complete. Most issues will fall under this category. Each Request should be easily assigned to one team. Some examples:

  • 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.
  • A bug on the website (more details below).

It's incredibly important that issues be broken into the smallest possible steps to complete. This helps keep velocity up and product development moving. If a Request involves more than one team or numerous steps to complete, consider turning it into a Main and breaking it down further.

Parent - Child Relationship

GitHub recently added the ability to mark issues as a Parent or Child. Using "Parent" on an Epic or Main and "Child" on the Requests attached to it make for easy tracking of all issues involved to finish a piece of work.

Pro tip: Check out How to Change Action Items into Child Issues

Bug

Bugs are unexpected problems, from minor glitches to major flaws, that are discovered throughout the development lifecycle, and handled independently of feature development. Expunge Assist has a Bug Report template that should be used when creating an issue about a bug. If you find a bug on the site, the Development team needs as much information as possible to be able to recreate it. This type of issue will ask lots of questions not only about what glitch you discovered, but also about the environment in which you spotted it, like which internet browser you were using and what operating system you're on. These are auto-assigned to the Dev lead to review before assigning to the team.

Structure of an Issue

The following describes what information is required when creating a new issue. For most new issues, use the 'Blank Issue' template.

Overview

The Overview should be a concise description of what the issue is and why we want to do it. This is an important space to put context for the issue, so those assigned to the issue can complete it as efficiently as possible. This section also acts as a User Story, which is an important part of product development. If you're having trouble writing an overview, try using this format to flesh out what we want to do and why we want to do it:

"As a [type of user], I want [to perform this action] so that [I can achieve this goal]."

Action Items

The action items are steps to complete the issue. Action items should not be long, complicated, or difficult to complete, and they need to be clear directives that anyone on the team who picks up an issue can understand easily. They should be a task that can be checked off. If an issue has numerous action items or involves more than one team, consider turning the issue into a Main or Epic. If you find yourself explaining details in an action item, consider moving that information to the Overview.

Resources/Instructions

This section should include any documentation needed to start working on the issue, as well as any deliverables from the issue. For example, a Design issue may have a document from Content with new copy for Design to use in a new design, and on completion of the issue, the Design team member who worked on the issue will add a link to the completed design in Figma. It's crucial for this section to include both Resources for working on the issue and deliverables created in the issue for easy tracking.

Dependencies

If an issue can't be started until another issue is completed, that issue has a dependency. GitHub now has a dependency option in the Relationships section, so any new issue with a Dependency should be marked as "Add of change blocked by" with the issue that must be completed first. This can also be done the opposite way, where the issue to be completed first can be "Mark as blocking" under Relationships.

All issues with dependencies should be placed in the Icebox. We also currently mark all issues with a dependency with a dependency label, and the blocking issues is added to the text of the blocked issue, like so:

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

Labels

Hack for LA requires 6 labels on every issue to help sort the project board: size, priority, role, level, type, and feature. If you're ever unsure, there are 'missing' labels for each one, ie. 'size: missing'.

Size

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.

Priority

Priority is how important an issue is relevant to the other issues. We use a simple system: low, medium, and high.

Role

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.

Level

This describes the difficulty of an issue in relation to seniority or time spent as a HfLA volunteer. It's broken into three segments: Easy, Medium, Hard. Easy issues can be completed by the most junior team members and do not take a lot of skill or knowledge about the project. Hard should only be completed by skilled team members who are very familiar with the project, or with the help of a more senior team member. Medium falls somewhere in between.

Type

Type describes if the issue is an Epic, Main, or Request, as outlined above.

Feature

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

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

Only create a new feature label after speaking with a PM.

Milestones

Milestones are a goal agreed upon by the team, usually with a deadline. In order to make the status of the project more clear, PMs, along with the help of Team Leads, 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. Identifying issues that fall under the current milestone helps determine priority. These will be set by Team Leads and PMs.

Milestones may also be used by organization administrators to bucket groups of tasks/issues and see how the project is doing in these areas. Not all milestones follow a sequential order of release targets.

To avoid confusion, please consult your team's product manager on what is our current priority. (Currently our only priority and true milestone is 00. Stakeholder Review).

Explanation of current milestones

A list of our milestones can be found here

00. Stakeholder Review 2.0

As of Jan 1, 2025, our primary milestone is currently 00. Stakeholder Review 2.0.

Process of Creating an Issue

It all starts here. ✨

Choosing a Template

For the majority of issues, use the Blank Issue template.

You can reach the issues template page here or through the green New Issues button on the Issues page.

Other templates you may need to use:

  • Bug Report: for any bugs discovered on the site
  • Pre-work [Team]: these are created by PMs or Team Leads for new team members when they're onboarding
  • Onboarding/Offboarding: these are used by PMs or leads for onboarding or offboarding of members for specific teams, but will be made obsolete when the new onboarding process goes into practice (expected late 2025)

Filling out the Issue

Adding The Background

Noting the Dependencies

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.

Writing the Overview

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?

Writing Action Items

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.

Adding Resources/Notes

This space is particularly for any assets needed to complete the issue or any deliverables created from the issue.

Adding Assignees

Do not automatically assign someone to an issue, unless it is an issue you created to complete yourself. PMs and Team leads will assign the appropriate team member, or a team member can pick up an issue they want to work on.

Choosing Labels

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.

Adding the Project

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.

Adding the Milestone

If you are aware of the milestone we are currently working toward, add it. Otherwise, Team Leads and PMs will add it.

Resources

Example Issues

Epic: #1135

Issue Hierarchy

Grey lines show the hierarchical relationship between issues. The purple lines show dependencies.