RFC: Transitioning from Bugzilla to GitHub Issues

[makubacki]

RFC: Transitioning from Bugzilla to GitHub Issues

Revisions

• December 19, 2024
  • Add "Code First" checkbox to each issue form.
• November 12, 2024
  • Add a note to the end of the RFC that states bug emails will no longer be sent to the edk2bugs mailing list.
• November 11, 2024
  • Add "Mapping Bugzilla Items to Destination GitHub Repos" section to describe BZ criteria used to map issues.
• August 26, 2024
  • Updated "Replacements for Existing Use Cases" to describe a process where code first issues would be tracked in a PR against the edk2 repository.
• August 16, 2024
  • Updated "Goals" to state that GitHub issues will apply to all active tianocore and tianocore-docs repositories for consistency across the organization. Note that the proposed forms in this RFC still only apply to edk2 and the form details for all of those repos will be based on these forms and reviewed at time of creation.
  • Added a section titled "Replacements for Existing Use Cases" to explain how various categories of issues filed on Bugzilla will be handled.
• August 12, 2024
  • Changed the "Bug Type" checkboxes in the bug report form from "Firmware" and "Non-Firmware" to "Firmware", "Tool", and "Unit Test".
  • Note: The edk2 fork UI prototype has been updated to expand the placeholder text in the "Steps to Reproduce" field to include how to acquire the source code, build, and flash an image on a platform to reduce ambiguity for a developer to reproduce the problem.
• August 5, 2024
  • Added a reference to prototype on edk2 fork.
• August 2, 2024
  • Revised the note on fixed multi-item selection to state that multi-selection is supported and will be used for some input items.
  • A new proposal was added to use the "Auto PR Assigner Workflow" to notify relevant maintainers via a notification in the form of a comment that is posted to the issue after creation.
  • Added a "Firmware or Non-Firmware Bug" selection to the bug template.
  • Changed "Targets Impacted" from a freeform textbox to a multi-select dropdown list.
    • Move "Targets Impacted" higher in the bug form.
  • Changed the field "Packages Affected" to "Packages Impacted".
  • Added a "Package Name" label to the automatically applied labels section.
    • Moved the "Packages Impacted" field from the top of the feature request form to after the "Alternatives Considered" field.
  • Removed the "Specifications Affected" field from the documentation request form.
    • These issues can be filed in the respective specification repo.
• July 31, 2024
  • Updated some form descriptions to state that multi-selection will be provided via check boxes since multi-select is currently not supported in GitHub Forms.
  • Added label definitions to the manual label section
• July 19, 2024
  • Initial RFC sent to mailing list and posted on GitHub discussion 5926.

---

Background

TianoCore currently uses Bugzilla as its issue tracking system. However, with the recent transition from a mailing list
based code contribution process to GitHub pull requests, there is a growing need and value to consolidate development
activities on a single platform.

This RFC proposes a process for transitioning from Bugzilla to GitHub issues to improve issue tracking and
engagement. Feedback is welcome to refine the process in a way that best meets the needs of the TianoCore community.

General information about GitHub issues is available in the GitHub Issues Guide.

GitHub issues bring many advantages, including:

• Automation
  • GitHub issues can use the same GitHub action based automation as pull requests, enabling the process to be more
    tailored to the project's needs. The same GitHub REST API can also be reused allowing for reuse of external
    automation tools and scripts that are used with extracting pull request information.
    • An example already in use in edk2 PRs today is the stale bot which auto closes stale PRs to reduce review noise
      and keep open issues relevant.
• Centralization of Issue Activity
  • GitHub issues automatically track the places they are mentioned such as comments, commits, and pull requests. This
    provides a central location for tracking the discussion and related work for an issue.
• Collaboration Features
  • GitHub issues support features like labels, milestones, and project boards, that enable better organization and
    tracking of issues if leveraged by the community.
• Consistent User Account
  • Users can use the same account for both code contributions and issue tracking, making it easier to identify and
    track that developer's contributions and related activities.
• Financial Cost Savings
  • Bugzilla requires dedicated hosting provided by TianoCore members. GitHub issues use the exact same
    infrastructure already used for code hosting with no additional cost.
• Dev Tool Support
  • Many of the tools already being used for GitHub based development support integrated issue tracking such as
    VS Code GitHub issue integration.
• Ease of Access:
  • GitHub issues are accessible to anyone with a GitHub account, simplifying the registration and tracking process.
• Emoji and Reaction Support
  • Community members can quickly vote on issues so the most upvoted can be sorted for awareness and prioritization. Emoji and reaction data can be externally queried and exported via the GitHub REST API.
• Integration with Git
  • GitHub issues are tightly integrated with Git repositories, making it easier to reference commits and individual
    code changess with permalinks.
• Issue Templates
  • GitHub issues support templates, enabling standardization of issue reporting and customized validation in the
    template.
• Longer Lived Accounts
  • Even after users leave their companies, their GitHub accounts remain active, reducing the loss of user history and
    accessibility to that user in the future.
• Markdown Support
  • GitHub issues support Markdown formatting, allowing for rich text formatting and embedding of images and links.
    This provides a consistent experience with the PR process.
• Pull Request Automation
  • GitHub issues can be linked to pull requests simply by including the issue number in the pull request description,
    enabling better tracking and visibility. The issue will automatically close when the pull request is merged
    preventing dangling issues.
• Visibility
  • GitHub issues are more visible to developers and users who are already using GitHub for code development. The
    number of active issues is visible at the top of the repository page.

Goals

1. More issues will be filed since registration and access is consolidated alongside the code repository.
2. Issues will have more relevant and frequently updated information due to the built-in integration to the repo code
   and pull requests.
3. The submission process will be streamlined with better opportunities for automation and customization.
4. Ultimately, developers will need to spend less effort to track and manage issues over time using built-in linking
   and auto close features.
5. For consistency, enable this process in all active tianocore and tianocore-docs repositories.

Replacements for Existing Use Cases

The TianoCore Bugzilla currently centralizes issues for a variety of project needs. This section shows how these issues will be managed in the future. Any issues migrated from Bugzilla will be directed to the new location stated below.

• EDK2 - Issues in the edk2 GitHub repository.
• EDK2 Code First
  • Code first items are proposed to be tracked in a PR against the edk2 repository. Where BZXXXX is used today to denote code that is in code first and not production ready, PRXXXX would be used in the PR.
  • The PR should be given the type:code-first label so it is identifiable by both humans and code workflows as a code first PR. For example, this label could be used to prevent a PR from being merged if it is present. The label can be removed when the PR is ready to merge and the PRXXXX changes have been dropped.
• PI Specification spec items tracked as issues in the corresponding GitHub repository in the tianocore-docs organization.
• EDK2 Platforms - Issues in the edk2-platforms GitHub repository.
• EDK2 Test - Issues in the edk2-test GitHub repository.
• Tianocore Feature Requests - Feature request in the appropriate GitHub repository within the tianocore organization.
• Tianocore Security Issues - GHSA process in the edk2 GitHub repository.

Mapping Bugzilla Items to Destination GitHub Repos

This section shows the criteria that will be used to determine where a Bugzilla item is copied.

Repo	BZ Product
edk2	"EDK2" OR "EDK2 Code First" OR "Tianocore Feature Requests"
edk2-platforms	"EDK2 Platforms"
edk2-test	"EDK2 Test"

Note: There in the "Tianocore Feature Requests" product there are currently:

• 95 "Code" items
• 0 "Documentation" items
• 2 "Other" items
• 0 "Process" items
• 19 "Tools" items
• 1 "Web Content" item

Therefore, it is proposed all "Tianocore Feature Requests" items go to the edk2 repo where the majority of "Code" and "Tools" items apply, at least initially. Any issues that are not relevant can be manually transferred to other repos.

It is proposed that "Tianocore Security Issues" be transferred outside this direct process due to the sensitivity of those items and the need to accommodate special GHSA requirements.

Proposed Process

1. Create GitHub issue templates for the following categories that include basic automation of validation for input.

   • Bug Report
     • Fields:
       • Title
       • Is there an existing issue for this?
       • Bug Type - Firmware, Tool, and/or Unit Test
       • Code First Issue?
       • Packages Impacted
       • Targets impacted (if applicable) such as DEBUG/RELEASE/NOOPT/NO-TARGET
       • Current Behavior
       • Expected Behavior
       • Steps to Reproduce
       • Build Environment
         • Host Information (if applicable) such as OS and Tool Chain and/or container information
       • Version Information
         • Commit SHA or stable tag
       • Urgency
         • 🟢 Low
           • A minor change with little to no important functional impact
           • It is not important to fix this in a specific time frame
         • 🟡 Medium
           • An important change with a functional impact
           • Will be prioritized above low issues in the normal course of development
         • 🔥 High
           • A critical change that has a significant functional impact
           • Must be fixed immediately
       • Are you planning to submit a PR?
         • Yes
         • No
       • Do you need maintainer feedback?
         • Yes
         • No
       • Additional information including attachments (optional)
   • Feature Request
     • Fields:
       • Title
       • Feature Overview
       • Proposed Solution
       • Alternatives Considered (optional)
       • Packages Impacted
       • Urgency
         • 🟢 Low
           • A minor enhancement
           • It is not important to address this request in a specific time frame
         • 🟡 Medium
           • An important enhancement
           • Will be prioritized above low requests in the normal course of development
         • 🔥 High
           • A critical enhancement with significant value
           • Should be prioritized above low and medium requests
       • Are you planning to implement this feature?
         • Yes
         • No
       • Do you need maintainer feedback?
         • Yes
         • No
       • Code First Issue?
       • Additional information including attachments (optional)
   • Documentation Request
     • Fields:
       • Title
       • Request Description
       • Are you going to make the change?
         • Yes
         • No
       • Do you need maintainer feedback?
         • Yes
         • No
       • Code First Issue?
       • Additional information including attachments (optional)

   🗈 Note: A preview of the forms is available at New Issue - makubacki/edk2.
   🗈 Note: For fields, like package selection, multi-selection in a dropdown box will be used.

2. Automatically apply labels to the issue based on submission information:

   • Type

     • Bug Report
       • type:bug
         • Description: A software defect causing incorrect or unexpected behavior.
     • Feature Request
       • type:feature-request
         • Description: A suggestion or request for a new feature or enhancement to existing functionality.
     • Documentation Request
       • type:documentation-request
         • Description: A need for new or updated documentation, including user guides, spec modifications, or inline code documentation modifications.
         • Note: Zero or more package labels may be set based on what is selected in a given issue.
     • Code First
       • type:code-first
         • Description: An issue that is part of the code first process.

   • Urgency

     • Low
       • priority:low
         • Description: Little to no impact. No urgency to fix.
     • Medium
       • priority:medium
         • Description: Moderate impact. Should be prioritized over lower priority issues.
     • High
       • priority:high
         • Description: Significant impact. Should be fixed as soon as possible.

   • Package

     • Package Name
       • package:<PackageName>
       • Description: Represents a package that is relevant to the issue.

   • State

     • Needs Triage
       • state:needs-triage
       • Description: Needs to be triaged to determine next steps.
     • Maintainer Feedback Requested
       • state:maintainer-feedback-requested
         • Description: Needs more information from a maintainer to determine next steps.
     • Submitter Not Planning to Complete
       • state:needs-owner
         • Description: Needs an issue owner to be assigned.

     🗈 Note: While these labels will be applied automatically upon issue submission, any of them can be added manually as well.

3. Define GitHub labels that can be manually added:

   • Duplicate
     • state:duplicate
       • Description: An issue or pull request already exists for this topic.
   • Help Wanted
     • state:help-wanted
       • Description: Extra attention (collaboration) is needed.
   • Insufficient Submitter Information
     • state:needs-submitter-info
       • Description: Needs more information from the submitter to determine next steps.
   • Decision Not to Fix
     • state:wont-fix
       • Description: The issue is understood but will not be fixed.
   • Issue is Understood But Invalid
     • state:invalid
       • Description: The issue is understood but the use case is not valid.
   • Issue is Not Actively Being Fixed
     • state:backlog
       • Description: Not actively being worked on. Protected from stale cleanup by stale bot.
     • Note: This would also prevent the stale bot from closing the issue due to inactivity.

4. Define GitHub milestones for the upcoming three edk2 stable tags so that issues can optionally be tracked
   against those milestones.

   Note: The milestone box is a simple drop down that allows for easy selection of defined milestones.

5. Enable basic GitHub actions for GitHub issues:

   1. Automatic application of labels based on issue template input at time of issue creation.
   2. Daily check for issues that have not been updated in 45 days to apply the state:stale label (already used for
      pull requests in edk2) and leave a warning comment. If still no activity in 7 days, close the issue with a
      comment that it can be reopened if the issue is still relevant.
   3. Automatic notification of reviewers for the packages impacted by the issue. This will reuse existing functionality
      from the Add Pull Request Reviewers workflow already in use.

6. Stage updates to the TianoCore documentation to reflect the new process and provide a user guide for transitioning
   to GitHub Issues from Bugzilla.

7. Establish a date to begin accepting GitHub issues and disable the creation of new issues in Bugzilla. This RFC proposes
   the date of Monday, August 26, 2024 the following business day after the 202408 stable tag
   is released.

8. Communicate this date to the community alongside the staged documentation.

9. Enable GitHub issue submission in edk2 on the transition date.

10. Learn from GitHub issue usage and adjust the process as needed.

11. During this first one month, review open issues in Bugzilla to determine if they are still relevant and if so,
    transfer them to GitHub issues. Close the Bugzilla issue with a link to the new GitHub issue. This is possible to do
    programmatically.

12. Manually review the transferred issues to ensure accuracy and completeness.

---

After the transition to GitHub issues is made bugs will no longer be posted to bugs at edk2.groups.io. GitHub issues can be subscribed to if you would like to receive automated notifications.

Additional Resources

• GitHub Issues Documentation: GitHub Issues Guide
• Tracking Work with GitHub Issues: GitHub Issues - About issues
• GitHub Markdown Guide: Mastering Markdown

[makubacki]

There is an open suggestion to move all Bugzilla items in one migration and then mark Bugzilla read-only on the transition date. That is being investigated.

[makubacki]

I have a live prototype of the GitHub issue forms proposed in my fork: https://github.com/makubacki/edk2/issues/new/choose

This demonstrates what the form UI itself will look like. The automation flows to automatically apply certain labels based on input criteria will be added in the future.

[Conan-Kudo]

An example already in use in edk2 PRs today is the stale bot which auto closes stale PRs to reduce review noise
and keep open issues relevant.

I think we shouldn't be doing this. Generally "stale bots" are looked upon unkindly because "staleness" is not necessarily in the submitter's control, but instead the maintainer's side. For some people (myself included), it's considered highly disrespectful to use such tools to shut down issues and pull request submissions.

[makubacki]

The stale bot exists to bring attention to submissions that need attention. Currently, it will only mark a PR stale after 60 days of no activity. Leaving a comment, pushing, etc. by anyone, including the contributor, counts as activity. At the 60-day mark, the PR is left open, but a comment is posted indicating that the PR will be closed in 7 days if no further activity is made. If activity is made, the stale counter is reset. For example:

As demonstrated in this recent example, this was able to get reviewer attention to progress the PR. In a practical sense, this cleans up the many PRs created for simply testing CI (which should be marked draft now, but that's not guaranteed), but it also prevents contributions from being ignored for an unreasonable amount of time from submission time.

[bexcran]

The transition from Bugzilla to GitHub Issues has been completed, so I think this discussion can be closed now?

[makubacki]

Yes, thanks for the reminder. For reference the details of the transition are in #6544.