Skip to content

Issue Types

Jump to bottom
Ben Jarmak edited this page Apr 27, 2023 · 4 revisions

1. Overview

While GitHub only has 1 issue type, we apply our own layers on top of the base issue. This comes in 2 primary ways:

  1. Functional Breakdown
    • The function of the issue, is it a bug, question, feature request, or documentation request?
  2. Hierarchical Breakdown
    • How does this issue fit in with other ones? Think Epics vs. Stories

2. Scope

This document covers the functional issue types, as well as the hierarchy we are imposing ontop of GitHub issues.

Intended Audience: Project leads | Developers

3. Related Processes

4. Process/Main Body

Functional Issue Types

Bugs

Defects causing incorrect or unexpected behavior. We prioritize bugs based on their severity and impact, with a focus on maintaining software quality, reliability, and stability.

For a bug issue to be complete, it must:

  • Use our bug report template
  • Include a minimal reproducer
  • Include environment information
  • Include relevant log output

Feature Requests

Suggestions for new functionality or improvements to existing functionality. During triage we evaluate based on end-user value and alignment with our vision, then prioritize in the project.

For a feature request to be complete, it must:

  • Use our feature request template
  • Define if it's a new feature or an improvement
  • Include a clear description of the feature
  • Include reasoning for the request

Documentation Requests

All things creating or updating our documentation (user guides, sample code, API documentation). Our documentation evolves iteratively alongside the software, with requests prioritized in the product backlog to keep documentation relevant and up-to-date.

PRs should either update documentation when possible, or include the creation of a documentation request issue to ensure the need is not lost.

For a documentation request to be complete, it must:

  • Use our documentation request template
  • Define if it's a correction, or new documentation
  • State the required documentation

Questions

Questions are generalized items that don't fit into the above functional types. They may be:

  • General Q&A for the team
  • Questions about future development
  • Team discussions on a future approach
  • Team discussions on a potential breaking change

We now use GitHub Discussions for questions - if one comes in, please convert it to a discussion and continue the thread there.

Hierarchical Breakdown

Below is a chart showing the traditional agile issue hierarchy using Themes, Epics, Stories, and Tasks.

graph TD
  %% Theme 1
  A1[Theme 1]

  %% Epic 1
  B1[Epic 1.1]
  A1 --> B1

  %% User Stories for Epic 1
  C1[Story 1.1.1]
  C2[Story 1.1.2]
  B1 --> C1
  B1 --> C2

  %% Tasks for Story 1.1.1
  D1[Task 1.1.1.1]
  D2[Task 1.1.1.2]
  C1 --> D1
  C1 --> D2

  %% Tasks for Story 1.1.2
  D3[Task 1.1.2.1]
  D4[Task 1.1.2.2]
  C2 --> D3
  C2 --> D4

  %% Epic 2
  B2[Epic 1.2]
  A1 --> B2

  %% User Stories for Epic 2
  C3[Story 1.2.1]
  C4[Story 1.2.2]
  B2 --> C3
  B2 --> C4

  %% Tasks for Story 1.2.1
  D5[Task 1.2.1.1]
  D6[Task 1.2.1.2]
  C3 --> D5
  C3 --> D6

  %% Tasks for Story 1.2.2
  D7[Task 1.2.2.1]
  D8[Task 1.2.2.2]
  C4 --> D7
  C4 --> D8
Loading

While we cannot explicitly create these issue types in GitHub, we can effectively make them through the use of tasklists and title tagging. A benefit of the lack of hierarchy in GitHub is that we can use whatever depth of hierarchy we need at any given time.

A tasklist essentially turns any issue into a parent of child issues/PRs. In the above diagram:

  • Theme 1 has a tasklist that links to Epic 1.1 and Epic 1.2
  • Epic 1.2 has a tasklist that links to Story 1.1.1 and Story 1.1.2
  • Story 1.1.1 has a tasklist that links to Task 1.1.1.1
  • Task 1.1.1.1 is a bottom-level issue, nothing depends on it and it doesn't describe any further work

Setting up tasklists does a few things:

  • In children issues, they get a badge that says Tracked by #1234 with quick linkage back
  • In Projects, turning on the Tracks column gives a completion visual, showing how far along the tracked tasks are
    • This is a powerful view for stakeholders and PiC roadmapping
  • In Projects, we can filter or group based on tracking status
    • Grouping by Tracked-By creates a grouped view where the parent issue is the group title
    • Unfortunately today, Projects do not support groups within groups, so instead of seeing
      • Theme 1
        • Epic 1.1
          • Story 1.1.1
            • Task 1.1.1.1
    • We would see:
      • Theme 1
        • Epic 1.1
        • Epic 1.2
      • Epic 1.1
        • Story 1.1.1
        • Story 1.1.2
      • Story 1.1.1
        • Task 1.1.1.1
        • Task 1.1.1.2

Themes

High-level categories or groupings of related features or functionality that align with the overall goals or objectives of the software project. Themes help to provide context for the features being developed, and ensure that they are aligned with the needs of the end users or customers.

Theme will often span multiple releases, or be the focus of an entire release. They are created and curated by project leads.

Theme issues must:

  • Have their title begin with [THEME]
  • Provide readers a strong understanding of "why?"
  • Describe the goal of the theme
  • Define success criteria

Releases as Themes

It can be beneficial to track all Epics/Story-level issues within a release through a theme. This provides two primary benefits

  1. People who are uncomfortable with the project views may prefer to see everything listed within a single issue
  2. This provides the ability to create a grouped timeline/roadmap view in the project for each release, showing development over time

Epics

Large features or functionality - epics are defined in terms of goals and requirements, and represent a significant investment of time and effort. Epics help to organize and prioritize development work, and can be used to track progress and report on overall project status.

Epic issues must:

  • Have there title begin with [EPIC]
  • Describe the goal of the epic
  • Define success criteria
  • Define how it progresses its parent theme, if applicable
    • Not all epics must have Themes

Epic Issue Template

# Summary
<!-- A few sentences that provide a high-level summary of "what" and "why" -->

# Intended Outcome
<!-- What is the desired result, regardless of how it is accomplished? -->

 ```[tasklist]
# Tasks
- [ ] 
 ```
# Related Info
<!-- Any additional background information, especially links to prior issues/PRs -->

Stories and Tasks

For our purposes, there is very little difference between stories and tasks - they define specific functionality, and we use that to build a PR that answers the issue.

Our goal is to break down work to be able to be completed within a maximum of 1 sprint (2 weeks). If it cannot be completed during that time, it should be broken down into smaller components and linked with a tasklist.

Tasks and stories follow the Bug/Feature Request/Documentation Request requirements in the Functional Breakdown section.

5. References/Appendix

This section intentionally left blank.

Home

CCCL Execution Processes

CCCL Strategic Processes

Clone this wiki locally