rfc:github_issues

This is an old revision of the document!


PHP RFC: Migrating to GitHub Issues

  • Date: 2021-11-01
  • Author: Nikita Popov nikic@php.net
  • Status: Draft

Introduction

This RFC proposes to use GitHub Issues on the PHP repository in place of our own bugs.php.net bug tracker.

Currently GitHub issues are already used for documentation issues, as well as website issues on the respective repositories. This RFC expands usage to the PHP implementation itself.

Motivation

The primary motivation for this change is that bugs.php.net has many known deficiencies and is not actively maintained.

TODO

Proposal

The issue tracker on GitHub will be located on the php/php-src repository. The necessary configuration and actions for the setup described in the following are available in a test repository.

Issue Creation Flow

Using a custom issue configuration, creating an issue will display three possible options:

Options when creating an issue

Bug reports and feature requests are filed on GitHub with custom issue forms. Security issues point to bugs.php.net instead, because GitHub currently does not support private issue reports. Additionally, we could add a fourth option for general questions that points to our support page.

If the “bug report” option is chosen, the following form is displayed:

Bug report form

It requires an issue title, description and PHP version, and optionally accepts the used operating system. The description suggests (but does not require) to provide a script with actual and expected output. Additionally, the labels “bug” and “Status: Needs Triage” are automatically applied.

The corresponding form for feature requests only accepts an issue title and description, as PHP version and operating system are usually not relevant in this case. The labels “feature” and “Status: Needs Triage” are automatically applied.

Triage and Categorization

Issues labeled with “Status: Needs Triage” should be reviewed by a member of the php-src team to check whether they are valid (at first glance) and properly categorize them. When the issue is triaged, the “Status: Needs Triage” label is removed and replaced by one or more categorization labels. There are three sets of these:

  • “Extension: ext_name” correspond to bundled PHP extensions. For most extension-related issues, just adding the label for the corresponding extension is sufficient, e.g. “Extension: curl” for curl-related issues.
  • “SAPI: sapi_name” correspond to bundled SAPIs. These should be added if the issue is directly related to the SAPI, e.g. “SAPI: fpm” should be used for FPM-related bugs. It should not be added if the reporter just happens to use this SAPI, but there is otherwise no direct relation.
  • “Category: category_name” exists for categories that correspond either to a subset of an extension (e.g. “Category: JIT”) or represent cross-cutting concerns (e.g. “Category: Build System”). These might be applied in addition to or in place of an extension label.

The full set of initially proposed labels is given in the following, but additional labels can easily be added after the fact:

  • Extension: bcmath
  • Extension: bz2
  • Extension: calendar
  • Extension: com_dotnet
  • Extension: ctype
  • Extension: curl
  • Extension: date
  • Extension: dba
  • Extension: dom
  • Extension: enchant
  • Extension: exif
  • Extension: ffi
  • Extension: fileinfo
  • Extension: filter
  • Extension: ftp
  • Extension: gd
  • Extension: gettext
  • Extension: gmp
  • Extension: hash
  • Extension: iconv
  • Extension: imap
  • Extension: intl
  • Extension: json
  • Extension: ldap
  • Extension: libxml
  • Extension: mbstring
  • Extension: mysqli
  • Extension: mysqlnd
  • Extension: oci8
  • Extension: odbc
  • Extension: opcache
  • Extension: openssl
  • Extension: pcntl
  • Extension: pcre
  • Extension: pdo (core)
  • Extension: pdo_dblib
  • Extension: pdo_firebird
  • Extension: pdo_mysql
  • Extension: pdo_oci
  • Extension: pdo_odbc
  • Extension: pdo_pgsql
  • Extension: pdo_sqlite
  • Extension: pgsql
  • Extension: phar
  • Extension: posix
  • Extension: pspell
  • Extension: readline
  • Extension: reflection
  • Extension: session
  • Extension: shmop
  • Extension: simplexml
  • Extension: snmp
  • Extension: soap
  • Extension: sockets
  • Extension: sodium
  • Extension: spl
  • Extension: sqlite3
  • Extension: standard
  • Extension: sysvmsg
  • Extension: sysvsem
  • Extension: sysvshm
  • Extension: tidy
  • Extension: tokenizer
  • Extension: xml
  • Extension: xmlreader
  • Extension: xmlwriter
  • Extension: xsl
  • Extension: zend_test
  • Extension: zip
  • Extension: zlib
  • SAPI: apache2handler
  • SAPI: cgi
  • SAPI: cli
  • SAPI: cli_server
  • SAPI: embed
  • SAPI: fpm
  • SAPI: fuzzer
  • SAPI: litespeed
  • SAPI: phpdbg
  • Category: Arrays
  • Category: Build System
  • Category: Engine
  • Category: Filesystem
  • Category: JIT
  • Category: Math
  • Category: Streams
  • Category: Strings
  • Category: Windows

Members of the php-src team can adjust labels directly when submitting an issue, so they can bypass “Status: Needs Triage” and directly categorize the issue as appropriate.

Issue Statuses and other labels

GitHub only supports “open” and “closed” issues, so additional status information is handled through a number of labels:

  • Status: Needs Triage. As discussed above, this is the starting state for all new issues. The label is removed after triage by a team member.
  • Status: Needs Feedback. This label can be placed if additional feedback from the reporter has been requested. The label is automatically removed if the issue reporter adds a comment. If no comment is added within 14 days, the issue is automatically closed. This functionality is implemented using GitHub Actions workflows.
  • Status: Verified. Indicates that a bug report has been reproduced and confirmed to be an actual bug.
  • Status: Duplicate / Invalid / Won't Fix. These indicate that an issue has been closed without fixing it, because it is a duplicate of another issue, not a bug or will not be fixed/implemented.

GitHub has announced that they will add support for indicating whether an issue has been closed because it has been fixed or because it is in some way invalid. Once this functionality is rolled out, the need for the last set of status labels may go away.

Finally, the standard “good first issue” label can be used to indicate issues that are probably friendly to new contributors.

Referencing issues

Issues on GitHub can be referenced as #123 in the same repository or php/php-src#123 from a different one. A problem with the #123 notation is that it creates an ambiguity between the issues ID on GitHub and old issue IDs on bugs.php.net, which can and will clash. This is not a problem for references in comments (where it is understood that #123 always refers to a GitHub issue or pull request, and references to bugs.php.net should be made with an explicit link), but is a problem for commit messages: Fixes #123 could refer to two different issues.

For this reason, it it proposed that GitHub issues should be referenced using GH-123 from commit messages, as well as the NEWS file, while bugs.php.net references should continue to use bug #123.

# NEWS file
- Core:
  . Fixed GH-12345 (GitHub issue title). (Author)
  . Fixed bug #12345 (bugs.php.net bug title). (Author)

# Commit messages
Fixed GH-12345: GitHub issue title
Fixed bug #12345: bugs.php.net bug title

The use of “Closes GH-12345” is already standard practice to close the associated pull request when manually merging.

A redirect from https://php.net/GH-12345 to https://github.com/php/php-src/issues/12345 should be set up as well, to make it easier to look up issues by GitHub ID.

Other

GitHub supports saved replies, which can be used to remember commonly used responses. Unfortunately, saved replies can only be configured per-user, it is not possibly to specify a set of default responses for a repository. This may still be individually useful for people commonly performing triage.

GitHub also supports milestones, which we currently use to loosely track pull requests that should go into a certain PHP version. It would be possible to add all issues reported against a certain PHP version to the appropriate milestone, which would make the issues more reliably filterable by version. I do not propose to do this, because many issues are not version specific and their “affected version” is a moving target (usually lowest supported). However, release managers may find it useful to track issues relating to a new minor version in the pre-release phase.

Issues can be transferred to a different repository in the same organization, so it is possible to move issues between php/php-src and php/doc-en, if bugs or documentation problems are reported in the wrong place.

Migration of existing issues

Existing issues on bugs.php.net will not be migrated to GitHub issues under this proposal. While new (non-security) issues on bugs.php.net will not be accepted, commenting on old bugs will continue to be allowed for the time being, and bug reports should be made available in read-only form indefinitely.

If a bug is reported on GitHub issues which already has a report on bugs.php.net, then the bugs.php.net report should be closed as a duplicate of the GitHub issue and any valuable information from it briefly summarized there. Over time, bugs that still exist and are still relevant will converge to GitHub issues.

We do not attempt to perform a mass migration for two primary reasons: First, the vast majority of old bug reports are not relevant to active development. It is important that historical reports remain available, but importing a copy of them into GitHub is not particularly helpful, especially as references in commits and tests will use the bugs.php.net ID, not the GitHub issues ID. It might make some sense to import open bugs only, though even there a large fraction will not be relevant to active development.

Second, there are large mismatches in capabilities and usage between bugs.php.net and GitHub issues, so that imported issues tend to have cluttered presentation and timelines. For example, this is how an imported issue in the Go repository looks like: https://github.com/golang/go/issues/1691

bugs.php.net

Per the above, bugs.php.net will remain active for the following purposes:

  • Reporting of security issues against PHP.
  • Reporting of issues against PECL extensions. (We may want to discontinue this as well. Many actively maintained extensions already use GitHub issues rather than bugs.php.net.)
  • Commenting/updating on existing issues.

However, the following will no longer be accepted:

  • Reporting documentation problems. (Already disabled.)
  • Reporting non-security issues against PHP.

Some effort will still have to go into maintaining bugs.php.net. In particular, as comment spam is a major problem for us and comments will continue to be supported, we will have to add stronger spam protection there. As this will be legacy system we can degrade user experience though, e.g. by using reCaptcha.

rfc/github_issues.1635846412.txt.gz · Last modified: 2021/11/02 09:46 by nikic