rfc:third-party-code

Differences

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

Link to this comparison view

Next revision		Previous revision
rfc:third-party-code [2024/09/28 05:23] – created crellrfc:third-party-code [2024/11/23 19:23] (current) – Close the vote crell
Line 1: Line 1:
 ====== PHP RFC: Policy on 3rd party code ====== ====== PHP RFC: Policy on 3rd party code ======
   * Version: 0.9   * Version: 0.9
-  * Date: 2013-02-24 (use today's date here)+  * Date: 2024-10-02
   * Author: Larry Garfield (larry@garfieldtech.com)   * Author: Larry Garfield (larry@garfieldtech.com)
-  * Status: Draft (or Under Discussion or Accepted or Declined)+  * Status: Approved
   * First Published at: http://wiki.php.net/rfc/third-party-code   * First Published at: http://wiki.php.net/rfc/third-party-code
  
Line 15: Line 15:
 ===== Proposal ===== ===== Proposal =====
  
-==== PHP tooling ==== 
  
-PHP tooling (the PHP.net website, first-party marketing material, the documentation generator project PhD, etc.) MAY make use of existing third party libraries and tools (collectively "libraries"), provided that the library meets all of the "Inclusion" criteria, and does not meet any of the "Exclusion" criteria.+The specific policy to adopt is documented precisely in this Pull Request: https://github.com/php/policies/pull/10
  
-Inclusion criteria:+In the interest of avoiding confusion by having multiple versions of it, this RFC will not repeat what is listed there.
  
-  - The library must have a stable >= 1.0 release, and have had one for at least a year.  (This is to ensure it has longevity.) +===== Discussion =====
-  - The library provides targeted, necessary functionality. +
-  - The library is a recognized de facto standard, or one of a small number of de facto standards, in its problem space. +
-  - The library is available under an MIT, BSD, LGPL, or GPL license.+
  
 +This section is non-normative.  It is a discussion of how this RFC author feels the above criteria would apply to various packages, as a way to demonstrate the expected thought process.
  
-Exclusion criteria:+  * Composer - It's 2024.  Composer is the sole project in its market, and is used by the overwhelming majority of the PHP ecosystem.  It is the only way to access the vast majority of the PHP ecosystem.  We should use it, we should document it, we should promote it. 
 +  * Symfony/Yaml - I am not aware of any other Yaml library in widespread use.  This is the de facto standard way to parse YAML in PHP, and has been for years.  It would be fine for PHP tooling to make use of it.  However, whether or not it is of broad enough interest to be mentioned in the documentation is debatable.  I would likely lean no.  It may make sense in marketing, potentially. 
 +  * Ramsey/uuid - This has long been a staple of UUID handling in PHP.  It would be fine for tooling to use.  More recently, Symfony/UUID has also come along, and though less used is still stable.  If the documentation were to mention UUID handling, it would be prudent to list both as options.  However, it is debatable if UUID handling is of broad enough interest for documentation.  It may make sense in marketing. 
 +  * Symfony, Laravel, Slim, Yii,WordPress, Drupal, TYPO3, etc. - While Laravel and Symfony are the market leaders in PHP frameworks, and WordPress dominates the CMS-oid market, it is a highly dynamic market, with literally dozens of players that have reasonable use.  That makes listing them in the documentation without "playing favorites" essentially impossible, and therefore none should be listed by name.  They should also not be used directly to build any PHP tooling, again to avoid the appearance of endorsement.  However, it may make sense to list several of them in passing in marketing material, explicitly noting that they are just some among many options. 
 +  * Serializers - This is another market with many viable players of various sizes, so we should not "endorse" any in particular via the documentation.  It may or may not make sense for marketing material, but definitely not documentation.  However, any of the major supported ones are fair game for tooling to leverage as appropriate. 
 +  * PHPStan, Psalm - These are, to my knowledge, the only serious players in the static analysis space that meet the above criteria.  It's entirely reasonable, and encouraged, for tooling to make use of them.  We can also document both under the heading of "static analysis tools, they're a good idea", without saying people should use one instead of the other.  This would be fair game for both documentation and marketing material.
  
-  - The library is a "full" framework +===== Open Questions =====
-  - The library is available under an AGPL license. +
-  - The library is not available under an Open Source license. +
-  - The library has shown no meaningful activity for one year prior to its first inclusion. +
- +
- +
-PHP tooling maintainers MAY use their judgement to determine if a library meets the above criteria, but SHOULD be conservative in their interpretation of whether or not a library satisfies the necessary criteria. +
- +
-==== PHP documentation ==== +
- +
-Documentation hosted on the PHP.net website, first-party marketing material, and other public facing text (collectively "documentation") MAY reference and link to third party libraries and tools (collectively "libraries"), provided that the library meets all of the "Inclusion" criteria, and does not meet any of the "Exclusion" criteria.  Additionally, the language used to refer to the library must also follow the criteria below. +
- +
-Inclusion criteria: +
- +
-  - The library must have a stable >= 1.0 release, and have had one for at least a year. +
-  - The library provides a use that is commonly needed by numerous types of projects, and a reasonable estimate would make it relevant to at least 40% of the PHP ecosystem. +
-  - The library is a recognized de facto standard, or one of a small number of de facto standards, in its problem space.  If there are a small number of de facto standard libraries, then all should be listed and given equal weight. +
-  - The library is available under an Free Software license (as defined by the Free Software Foundation). +
-  - The language used to describe the library does not imply that the PHP Project is involved in or specifically recommends the library over some other. +
- +
- +
-Exclusion criteria: +
- +
-  - The library is one of many (more than ~4) viable options in its problem space, even if it is the most common of those many options. +
-  - The library is not available under an Open Source license. +
-  - The library has shown no meaningful activity for one year prior to its first mention. +
-  - The library is not of broad interest to the PHP ecosystem. +
- +
-PHP documentation maintainers MAY use their judgement to determine if a library meets the above criteria, but SHOULD be conservative in their interpretation of whether or not a library satisfies the necessary criteria. +
- +
-==== Conflict resolution ==== +
- +
-Should there be a reasonable dispute as to whether a given library satisfies the criteria above, an RFC may be posted to explicitly approve the library for either use or reference.  The RFC MUST have a 2/3 vote threshold to approve the library.  If the library is rejected, it may be revisited after six months, like any other RFC. +
- +
-==== Initially approved libraries ==== +
- +
-The following packages are explicitly approved for use by this RFC, as they meet all of the criteria above. +
- +
-  * Composer +
-  * PHPUnit +
-  * Xdebug +
-  * PHPStan +
-  * Psalm +
-  * Any library or PSR published by the PHP-FIG +
- +
- +
-===== Discussion ===== +
- +
-This section is non-normative.  It is a discussion of how this RFC author feels the above criteria would apply to various packages, as a way to demonstrate the expected thought process.+
  
-  * Composer - It's 2024.  Composer is the sole project in its market, and is used by the overwhelming majority of the PHP ecosystem.  It is the only way to access the vast majority of the PHP ecosystem.  WE should use it, we should document it, we should even promote it. +  - It likely would not come up, but are we OK with using AGPL code in PHP tooling?  It's not like any of our code is inaccessible.
-  * Symfony/Yaml - I am not aware of any other Yaml library in widespread use.  This is the de facto standard way to parse YAML in PHP, and has been for years.  It would be fine for PHP tooling to make use of it.  However, whether or not it is of broad enough interest to be mentioned in the documentation is debatable.  I would likely lean no. +
-  * Ramsey/uuid - This has long been a staple of UUID handling in PHP.  It would be fine for tooling to use.  More recently, Symfony/UUID has also come along, and though less used is still stable.  If the documentation were to mention UUID handling, it would be prudent to list both as options.  However, it is debatable if UUID handling is of broad enough interest. +
-  * Symfony, Laravel, Slim, Yii, etc. - While Laravel and Symfony are the market leaders in PHP frameworks, it is a highly dynamic market, with literally dozens of players that have reasonable use.  That makes listing them in the documentation without "playing favorites" essentially impossible, and therefore none should be listed by name.  They should also not be used directly to build any PHP tooling, again to avoid the appearance of endorsement. +
-  * WordPress, Drupal, TYPO3, Concrete5, etc. - As with frameworks, this market is far too dynamic for us to document without tipping the scales.  We therefore should mention none, and use none. +
-  * Serializers - This is another market with many viable players of various sizes, so we should not "endorse" any in particular.  However, any of the major supported ones are fair game for tooling to leverage as appropriate. +
-  * PHPStan, Psalm - These are, to my knowledge, the only serious players in the static analysis space that meet the above criteria.  It's entirely reasonable, and encouraged, for tooling to make use of them.  We can also document both under the heading of "static analysis tools, they're a good idea", without saying people should use one instead of the other.+
  
 ===== Proposed Voting Choices ===== ===== Proposed Voting Choices =====
Line 91: Line 39:
 Simple 2/3 majority vote. Simple 2/3 majority vote.
  
 +<doodle title="Accept this policy proposal?" auth="crell" voteType="single" closed="true">
 +   * Yes
 +   * No
 +</doodle>
  
 ===== References ===== ===== References =====
  
-Links to external references, discussions or RFCs+ * [[https://news-web.php.net/php.internals/125732|Discussion on internals@]]
  
 ===== Rejected Features ===== ===== Rejected Features =====
  
  
rfc/third-party-code.1727501000.txt.gz · Last modified: 2024/09/28 05:23 by crell

Page Tools