Setting Up GitHub Issues

Table of Contents
  1. Introduction
  2. Feature issue
  3. Template issue
  4. Component issue
  5. Bug report issue
  6. Idea issue
  7. Task issue
  8. Documentation Issue
  9. QA Issue

Introduction

There are six issue types we’ve identified as being common to most projects. You’ll see templates for each of these issue types whenever you open a new issue on GitHub:

If you’re missing these templates in your repository, you can grab a copy from Responsive Child Starter’s GitHub folder.

Feature Issue

An official feature that has already been planned and accepted as part of strategy.

Examples:

  • BU Profiles (related issues: Profile Template, Profiles Shortcode, Profiles Archive Template, Profiles Post Type issue which may include new fields to be added to the post type )
  • BU Banners ( related issues: Default Layouts, Custom Event Banner Layout, a new profile post banner layout, looping background video layout )
  • BU Landing Pages ( related issues: BULP Template, One for each of the standard BULP sections, issues for custom BULP sections being added )
  • A custom post type – “Research Projects”. A custom post type is being added to organize research projects for a research center. This feature would have a number of issues related: Research Projects Custom Post Type, Research Projects Single Template, Research Projects Archive Template, Research Projects Shortcode to display research project posts in other pages. 

A feature issue contains a high level summary of the work to complete that feature. A feature issue may be a custom feature such as a new post type and its corresponding templates, or an existing plugin that adds a feature such as BU Profiles Plugin or BU Banners. The feature should describe the problem, how the feature solves it, and list all of the associated or child issues that make up the work needed to complete that feature.

Issue Structure:

  • These items may appear on some feature issues:
    • Visuals: Rarely appear on the feature issue, but instead exist on the child issues such as BU Profiles Template.
    • A Goal: What is this feature trying to accomplish for the client?
    • Business Requirements: Non-technical, explanation, checklist, User Story, or other structure that defines how this feature needs to function to solve a need. It should include any functionality / design direction.
    • Technical Requirements: A technical explanation, checklist, or other structure that defines how this feature could be developed to meet the Business Requirements.
      • Does it relate to any feature being added to the site such as BU profiles?
      • Is it existing functionality or custom or challenging??
  • Related Issues: A list of related issues such as other components, post types, templates, shortcodes, etc that are needed to complete this feature should be linked here.
  • Labels: The 💡 Feature label should be applied, along with any related 🔌 Plugin labels.

    Example: https://github.com/bu-ist/id-github-demo/issues/21

     

    Template Issue

    An official template that has been planned for and accepted as part of strategy. A template may be an existing page template such as News, Page.php, Single.php (for news posts) or a custom page template such as “Research Projects” that lists Research Project posts.

    Templates also include templates applied to other post types, including custom post types. Examples might be BU Profiles Single Post Template, Archive.php, Taxonomy.php, BU Article Single Post Template (Prepress).

    Templates may be custom page templates the user can select and apply to a page, or templates that are applied to a type of data based on the WordPress Template Hierarchy.

    A template may include or contain one or more template-parts.

    Issue Structure:

    • Visuals: The issue should include screenshots, and/or links to Wireframes or Mockups for the template to be built.
    • Business Requirements: Non-technical, explanation, checklist, or other structure that defines how this template needs to function to solve a need. It should include any functionality / design direction.
    • Technical Requirements: A technical, explanation, checklist, or other structure that defines how this template could be developed to meet the Business Requirements.
      • Does it relate to any feature being added to the site such as BU profiles?
      • Is it existing functionality or custom or challenging?
      • Does this override an existing template?
    • Labels: 
        • The ⚙️ Template task type label should be applied, along with any related 🔌 Plugin labels.
        • ✅ Needs frontend and ✅ Needs backend labels should be added once the issue is ready to be acted on by that skillset. Remove these labels when frontend or backend are complete.

     

    Component Issue

    An official component that has been planned for and accepted as part of strategy.

    Examples: A shortcode, a gutenberg block, a metabox on a template, a BU Banner layout, template-part, etc. 

    A component issue makes up the bulk of the work on most projects. They represent the shortcodes, blocks, metaboxes, and other elements that we build. They should generally consist of Business Requirements written by the designer on the project and Technical Requirements written by the developer on the project. 

    Issue Structure:

    • Visuals: The issue should include screenshots, and/or links to Wireframes or Mockups for the element to be built.
    • Business Requirements: Non-technical, explanation, checklist, or other structure that defines how this element needs to function to solve a need. It should include any functionality / design direction. 
    • Technical Requirements: A technical explanation, checklist, or other structure that defines how this element could be developed to meet the Business Requirements. 
      • Does it relate to any feature being added to the site such as BU profiles? 
      • Is it existing functionality or custom or challenging? 
    • Labels: 
      • The appropriate ⚙️ Task type labels, such as Shortcode, Template-Part, Widget, etc, should be applied, along with any related 🔌 Plugin labels.
      • ✅ Needs frontend and ✅ Needs backend labels should be added once the issue is ready to be acted on by that skillset. Remove these labels when frontend or backend are complete.

    Example: https://github.com/bu-ist/id-github-demo/issues/22

     

    Bug Report Issue

    A defect or problem that needs to be tested, triaged, and possibly fixed. It should follow the issue template with as much detail as possible or necessary to explain the problem. A Bug issue can be created by the team when a QA issue is found, and/or created following a client bug report.

    Label: 💡 Bug or 🔥 Product bug should be added as appropriate. For products only, there is also a 🚦Project dependency label.

    Idea Issue

    Suggest an idea for this project to start a discussion and determine impact in a project early in the lifecycle of a project. Idea issues should be non-actionable. Out of that discussion may come a refinement of the idea and another issue would be created to define that work to be completed. Not all ideas will become actionable work.

    Issue Structure:

    • Fill out the issue template questions.
    • Labels: A 💡 Type: Idea Label should be applied.

    Task Issue

    An official task that has been planned for and accepted as part of strategy. A small task that must be done that is not a component, feature, template or other existing issue.

    Examples: “Import Resources Post Type functionality from old theme”, “Port old shortcode from r-something to new theme”

    • A ⚙️ Template task type label should be applied if applicable, along with any related 🔌 Plugin labels.
    • ✅ Needs frontend and ✅ Needs backend labels should be added once the issue is ready to be acted on by that skillset. Remove these labels when frontend or backend are complete.

     

    Documentation Issue

    Documentation that should be created for an accepted feature. Most often a documentation issue will be created for each release to document the issues in the release that should have documentation written and track the status of that documentation. Occasionally there may need a need to create a Documentation Issue specific to a certain complex feature to detail more specifics about what should be documented.

    Examples: Release 2 Documentation Issue might list a few shortcodes and custom page templates that need to be documented but not some other standard features such as the Calendar Template that don’t require project specific documentation.

    Issue Structure:

    • List of Issues to Document: These are some, but not necessarily all of the issues in this release that should be documented in the site’s documentation site. 
    • List of Documentation Pages: After creating the documentation, please add links to it in the Github issue so the team can review the documentation that was created.

     

    QA Issue

    QA Testing that should be performed for an accepted feature. Most often a QA issue will be created for each release to identify the issues in the release that should be tested for the release and track the status of that testing. Occasionally there may need a need to create a QA Issue specific to a certain complex feature to detail more specifics about what should be tested and how.


    Examples: Release 2 QA Issue might list a few shortcodes and custom page templates that need to be tested extensively for both browser rendering and functional behavior. It would also include other issues for standard features such as the Calendar Template that may only require browser testing.

    Issue Structure:

    • List of Issues to Test: The issues that need to be tested and if appropriate the type of testing that should be done.
    • List of Supported Browsers: The browsers that should be used for testing each feature.