rfc:github_issues

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
rfc:github_issues [2021/11/02 14:10] nikicrfc:github_issues [2021/12/04 14:22] (current) nikic
Line 2: Line 2:
   * Date: 2021-11-01   * Date: 2021-11-01
   * Author: Nikita Popov <nikic@php.net>   * Author: Nikita Popov <nikic@php.net>
-  * Status: Under Discussion+  * Status: Accepted
  
 ===== Introduction ===== ===== Introduction =====
Line 21: Line 21:
   * **Accessibility**: Nowadays, most open-source projects manage issues on GitHub and users will look there first. Submitting an issue on a home-grown bugtracker comes with additional friction to learn a new bug reporting workflow and its associated quirks (and bugs.php.net is on the quirkier side there).   * **Accessibility**: Nowadays, most open-source projects manage issues on GitHub and users will look there first. Submitting an issue on a home-grown bugtracker comes with additional friction to learn a new bug reporting workflow and its associated quirks (and bugs.php.net is on the quirkier side there).
   * **Management of reported bugs**: For bug reporters without a php.net account, managing their reported bugs is very inconvenient. Editing a bug requires a per-bug password, and you can't easily track all the bugs you have reported.   * **Management of reported bugs**: For bug reporters without a php.net account, managing their reported bugs is very inconvenient. Editing a bug requires a per-bug password, and you can't easily track all the bugs you have reported.
-  * **Mentions**: It's not possible to mention another php.net team member on bugs.php.net. The only way to ask someones opinion on an issue is to assign it to them, and there can only be one assignee.+  * **Mentions**: It's not possible to mention another php.net team member on bugs.php.net. The only way to ask someone'opinion on an issue is to assign it to them, and there can only be one assignee.
   * **Moving issues**: We are currently in an in-between state where implementation bugs are on bugs.php.net, while documentation bugs are on GitHub. It is common that an issue originally reported as an implementation bug turns out to be a documentation problem. We currently cannot easily transfer such an issue to GitHub. It is valuable to have the issues for all sub-projects on one platform to allow this kind of seamless movement. (Of course, this problem did not exist before documentation started using GitHub issues.)   * **Moving issues**: We are currently in an in-between state where implementation bugs are on bugs.php.net, while documentation bugs are on GitHub. It is common that an issue originally reported as an implementation bug turns out to be a documentation problem. We currently cannot easily transfer such an issue to GitHub. It is valuable to have the issues for all sub-projects on one platform to allow this kind of seamless movement. (Of course, this problem did not exist before documentation started using GitHub issues.)
-  * **References**: We already host our source code repositories on GitHub and make heavy use of pull requests there. Hosting issues on the same platform makes it easier to cross-reference issues, pull requests and commits. While commits closing a bug are automatically linked from bugs.php.net other references (e.g. from pull requests) are not visible on bugs.php.net unless they are manually added.+  * **References**: We already host our source code repositories on GitHub and make heavy use of pull requests there. Hosting issues on the same platform makes it easier to cross-reference issues, pull requests and commits. While commits closing a bug are automatically linked from bugs.php.netother references (e.g. from pull requests) are not visible on bugs.php.net unless they are manually added.
   * **Labels**: Bugs only support specifying a single package, there is no capability to apply multiple labels. For example, we have no way to mark beginner-friendly issues (the "probably easy" label on GitHub).   * **Labels**: Bugs only support specifying a single package, there is no capability to apply multiple labels. For example, we have no way to mark beginner-friendly issues (the "probably easy" label on GitHub).
-  * **Check boxes**: bugs.php.net does not support check boxes, or edits to the bug description. This makes it impossible to use bugs.php.net for tracking issueswhich consist of multiple sub-tasks.+  * **Check boxes**: bugs.php.net does not support check boxes, or edits to the bug description. This makes it impossible to use bugs.php.net for tracking issues which consist of multiple sub-tasks.
  
 ===== Proposal ===== ===== Proposal =====
Line 43: Line 43:
 {{:rfc:bug_report_3.png?direct|Bug report form}} {{:rfc:bug_report_3.png?direct|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. +It requires an issue title, description and PHP version, and optionally accepts the used operating system. The description suggests (but does not require) providing 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. 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.
Line 165: Line 165:
 ==== Referencing issues ==== ==== 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.+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 issue'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''. 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''.
Line 186: Line 186:
 ==== Other ==== ==== Other ====
  
-GitHub supports [[https://docs.github.com/en/github/writing-on-github/working-with-saved-replies/about-saved-replies|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 supports [[https://docs.github.com/en/github/writing-on-github/working-with-saved-replies/about-saved-replies|saved replies]], which can be used to remember commonly used responses. Unfortunately, saved replies can only be configured per-user, it is not possible 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. 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.
Line 207: Line 207:
  
   * Reporting of security issues against PHP.   * 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.   * Commenting/updating on existing issues.
  
Line 213: Line 212:
  
   * Reporting documentation problems. (Already disabled.)   * Reporting documentation problems. (Already disabled.)
 +  * Reporting of issues against PECL extensions. (Extensions should have their own issue tracker. Most of them already track issues on GitHub, not bugs.php.net.)
   * Reporting non-security issues against PHP.   * Reporting non-security issues against PHP.
 +
 +It may be possible to migrate security issues to GitHub as well, by making of use of the [[https://docs.github.com/en/code-security/security-advisories/about-github-security-advisories|security advisories]] feature. However, larger changes to the handling of security issues should be decided within the security response group, and as such are considered out of scope of this proposal.
  
 ===== Alternatives ===== ===== Alternatives =====
Line 219: Line 221:
 The switch to GitHub issues has two primary disadvantages: The switch to GitHub issues has two primary disadvantages:
  
-  * It binds the PHP project more firmly to the GitHub platform. We already host our repositories there and make use of pull request, but this would take additional functionality "out of our control". Of course, that is also kind of the point: We are bad at maintaining critical infrastructure ourselves and would rather someone else took care of it. Someone for whom it is part of their core business, rather than just a necessary annoyance.+  * It binds the PHP project more firmly to the GitHub platform. We already host our repositories there and make use of pull requests, but this would take additional functionality "out of our control". Of course, that is also kind of the point: We are bad at maintaining critical infrastructure ourselves and would rather someone else took care of it. Someone for whom it is part of their core business, rather than just a necessary annoyance.
   * GitHub issues is not a particularly sophisticated issue tracker solution. While it offers many useful features that bugs.php.net does not, it is also less customizable. For example, there is no support for custom metadata on issues beyond standard features like labels or milestones (though there probably [[https://github.com/github/roadmap/issues/277|will be]] in the future).   * GitHub issues is not a particularly sophisticated issue tracker solution. While it offers many useful features that bugs.php.net does not, it is also less customizable. For example, there is no support for custom metadata on issues beyond standard features like labels or milestones (though there probably [[https://github.com/github/roadmap/issues/277|will be]] in the future).
  
Line 230: Line 232:
 Of course, the suggestion to use GitHub issues in particular is not an accident: Of course, the suggestion to use GitHub issues in particular is not an accident:
  
-  * We already host repositories there and use pull requests (and use it for documentation issues). Having everything on platform allows everything to integrate smoothly. Cross-references work everywhere out of the box. Other platforms will likely not be able to offer the same level of integration.+  * We already host repositories there and use pull requests (and use it for documentation issues). Having everything on one platform allows everything to integrate smoothly. Cross-references work everywhere out of the box. Other platforms will likely not be able to offer the same level of integration.
   * GitHub has become the industry standard for open-source projects. Anyone with involvement in open-source is very likely to have an account there and be familiar with the main workflows. Using a different platform will likely require people to create a new account, learn the quirks of yet another issue tracker and have one more place to check for progress on reported issues.   * GitHub has become the industry standard for open-source projects. Anyone with involvement in open-source is very likely to have an account there and be familiar with the main workflows. Using a different platform will likely require people to create a new account, learn the quirks of yet another issue tracker and have one more place to check for progress on reported issues.
  
 The requirement for an alternative would be that a) it is hosted (i.e. the PHP project does not need to maintain infrastructure for it), b) has good GitHub integration and c) is "sufficiently better" than GitHub issues to make it worth using a separate product. As PHP does not have a particularly sophisticated issue tracking workflow, I'm doubtful that the tradeoff will be worthwhile. The biggest "advantage" of using a separate product is likely that it will make reporting bugs significantly harder for the casual user, which might make low-quality submissions less likely. The requirement for an alternative would be that a) it is hosted (i.e. the PHP project does not need to maintain infrastructure for it), b) has good GitHub integration and c) is "sufficiently better" than GitHub issues to make it worth using a separate product. As PHP does not have a particularly sophisticated issue tracking workflow, I'm doubtful that the tradeoff will be worthwhile. The biggest "advantage" of using a separate product is likely that it will make reporting bugs significantly harder for the casual user, which might make low-quality submissions less likely.
 +
 +===== Vote =====
 +
 +Voting started 2021-11-20 and ends on 2021-12-04.
 +
 +<doodle title="Migrate from bugs.php.net to GitHub issues as proposed?" auth="nikic" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
rfc/github_issues.1635862244.txt.gz · Last modified: 2021/11/02 14:10 by nikic