Issue Templates - hackforla/tdm-calculator GitHub Wiki

Issue Template Management

This wiki explains why and how to create an issue template and how to propose changes to existing ones in our repository

Why

Creating a structured issue ensures that all documentation follows a consistent workflow with proper approvals and tracking. This process maintains quality control and keeps all cross-functional teams informed about content changes

Table of Contents

How to Create a New Issue Template

Create a new issue

  • You will write the draft of your template in a comment on the issue.

1. Title your issue clearly

  • “Subject: [NAME OF ITEM]"

2. Create the Overview Section

  • Create statement that includes “[Replace with NAME OF ITEM]"

3. Create the Details Section

  • Add the following text 
    [Replace with INFORMATION OR OTHER DETAILS THAT WILL HELP WRITE DRAFT]

4. Include all Action Items from the template without modification

  • Create Checkboxes for All Action Items

5. Add all Relevant Resources

  • Add the following section at the bottom of the template 
    ### Resources
  • Add any Google Drive folder paths that seem necessary
  • Add appropriate Figma file(s)
  • Add the following at the bottom of the issue, if the template is likely to end up in the Stakeholder Release Deck 
    #### Staging and Release decks
- [Staging Deck](https://docs.google.com/presentation/d/1crZ3IxqA4hAu3qzD7ns93Ieuqjwh6wyEtuX_46cP-fg/)
   - [Staging slide, ISSUE NUMBER]
- Release Deck
   - [2025-MM-DD Release deck, slide ISSUE NUMBER]

6. Labeling

  • Identify appropriate labels that include (but are not limited to) role, feature, bug, dependency, level, deck, and size
  • Add missing milestone label

7. Get approval on your issue template draft

8. Submit a Pull Request

Submit a Pull Request Submit a pull request (PR) that adds the new template file

  • Reference the associated issue number in your PR description
  • Engage in discussion and respond to feedback during the review process

Proposing Changes to Existing Templates

1. Open an Issue for Discussion

Any proposed change to an existing template must start with an issue

  • Describe the change, its objective, and any alternatives considered
  • Copy a draft of the existing template into a comment
  • Copy that draft again, and then edit it with the new changes
  • Get signoff by senior PM
  • This ensures transparency and provides direction for the PR

2. Edit the Template

Make the necessary changes to the template file(s)

3. Submit a Pull Request

All edits to existing templates require a PR

  • Link the PR to the issue you opened
  • Provide a clear summary of the changes and respond to reviewer feedback

Example Template Issues

Example 1: Different but related templates

The examples below are for templates that are related but different. They both have steps to work on the FAQ content but the items under the Details section are different in both and specific to the desired outcome.

Example 1a: Content: FAQ database: Add content

  • This is a template that is used to create a new issue when content needs to be added to the FAQ
  • Issue created using this template: https://github.com/hackforla/tdm-calculator/issues/2513
  • The details section is different in that it has items related to writing NEW content for the FAQ

    Details

    The below text provides a general outline for the question and answer. Use it as the basis for writing new content for this FAQ.

    Question (draft)

    [Replace with PROPOSED QUESTION]

    Answer (draft)

    [Replace with PROPOSED ANSWER OR OTHER DETAILS THAT WILL HELP WRITE DRAFT]

  • The Action Items section is different in that it requires a draft of the category, question and answer for the FAQ
    • Write a draft of the category, question, and answer that would appear on the FAQ page

Example 1b: Content: FAQ database: Revise content

  • This is a template that is used to create a new issue when content in the FAQ needs to be revised
  • Issue created using this template: https://github.com/hackforla/tdm-calculator/issues/2393
  • The Details section is different in that it has items related to revising the current FAQ content, which needs more detail

    Details

    The below text provides a general outline for the question and answer. Use it as the basis for writing new content for this FAQ.

    Category Current

    [Replace with CURRENT CATEGORY]

    Question Current

    [Replace with QUESTION TEXT]

    Answer Current

    [Replace with ANSWER TEXT]

  • The Action Items section is different in that it requires the current category, question and answer in addition to the proposed revisions
    • Add the Current category, question, and answer that appears on the FAQ page
    • Add the proposed changes

Example 2: Bug Report

  • This is a template that is used to create a bug issues
  • Issue created using this template: https://github.com/hackforla/tdm-calculator/issues/2498
  • The top of this issue does not have an Overview instead it has the following before the action items

    Describe the bug

    Steps to Reproduce

    Actual Result

    Expected Result

    Device Configuration

Example 3: Role specific issues

Example 3a: Design Issue

Example 3b: Dev Handoff Issue

  • This is a template issue that is used to create issues for dev once a design issue has been finished
  • Issue created using this template: https://github.com/hackforla/tdm-calculator/issues/2527
  • The Action Items are specific for devs, there are links to where to find the screenshots in the design issue and the Figma page.

Key Points

  • All edits to existing templates require a pull request
  • Every pull request must have an associated issue to provide direction, context and approval