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/10/06 12:58] (current) – Improve wording again 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: Discussion
   * First Published at: http://wiki.php.net/rfc/third-party-code   * First Published at: http://wiki.php.net/rfc/third-party-code
  
Line 14: Line 14:
  
 ===== Proposal ===== ===== Proposal =====
 +
 +==== Definitions ====
 +
 +
 +**PHP tooling** refers to the code behind the PHP.net website, the documentation generator project PhD, the PHP wiki, and other similar systems.  In general, "PHP code run by PHP.net."
 +
 +**Documentation** refers to objective information about PHP, the PHP language, the PHP standard library, and PHP ecosystem hosted on PHP.net.  This may include reference material, tutorials, FAQs, and similar.
 +
 +**Marketing material** refers to content on PHP.net or similar sites intended to promote or evangelize PHP the language or ecosystem.
 +
 +**Libraries** refers to existing third party code packages or tools, either C extensions or PHP code, maintained by someone other than the PHP Internals team.  It also includes command line utilities used primarily by a developer.  It may also refer to non-profit PHP ecosystem organizations, such as the PHP Foundation or PHP-FIG.
 +
 +**Web Application** refers to a "full" web framework that provides end-to-end web application capabilities, or an installable complete application.  It does not refer to command line utilities used primarily by developers building applications.
 +
 +**Approved license** refers to a license [[https://www.gnu.org/licenses/license-list.en.html|approved by the Free Software Foundation]] as Free Software, and that is inbound compatible with GPLv3.
  
 ==== PHP tooling ==== ==== 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.+PHP tooling MAY make use third party libraries, provided that the library meets all of the "Inclusion" criteria, and does not meet any of the "Exclusion" criteria.
  
 Inclusion criteria: Inclusion criteria:
Line 24: Line 39:
   - The library provides targeted, necessary functionality.   - 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 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. +  - The library is available under an Approved License.
  
 Exclusion criteria: Exclusion criteria:
  
-  - The library is a "full" framework +  - The library is a Web Application 
-  - The library is available under an AGPL license. +  - The library is not available under an Approved 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.   - 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 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.
Line 39: Line 51:
 ==== PHP documentation ==== ==== 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.+Documentation MAY reference and link to third party 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: Inclusion criteria:
  
   - The library must have a stable >= 1.0 release, and have had one for at least a year.   - 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 provides a use that is commonly needed by many types of projects, making it of **broad interest** to 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 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 library is available under an Approved License.
   - 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.   - 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: 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 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 is a Web Application. 
 +  - The library is not available under an Approved License.
   - The library has shown no meaningful activity for one year prior to its first mention.   - 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.   - 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. 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.
 +
 +==== Marketing material ====
 +
 +Marketing material MAY reference and link to third party 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 many types of projects, making it of **significant interest** to 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 MAY be a Web Application, provided its mention clearly does not specifically endorse the Application.  If many options exist in a space that bears mention, the most common should be given equal exposure.
 +  - The library is available under an Approved License.
 +  - 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 not available under an Approved 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 marketing material 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 ==== ==== 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.+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 one or more of the above cases.  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 ==== ==== Initially approved libraries ====
  
-The following packages are explicitly approved for use by this RFC, as they meet all of the criteria above.+The following packages are explicitly approved for use by this RFC for all three use cases, as they meet all of the criteria above.
  
   * Composer   * Composer
Line 73: Line 106:
   * Psalm   * Psalm
   * Any library or PSR published by the PHP-FIG   * Any library or PSR published by the PHP-FIG
 +
 +Additionally, for historical reasons, Dokuwiki is explicitly approved for use despite it being a Web Application as defined above.
  
  
Line 79: Line 114:
 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. 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. +  * 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. +  * 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. +  * 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, 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. +  * 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. 
-  * 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 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. 
-  * 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.  This would be fair game for both documentation and marketing material. 
-  * 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.+ 
 +===== Open Questions ===== 
 + 
 +  - 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. 
 +  - 
  
 ===== Proposed Voting Choices ===== ===== Proposed Voting Choices =====
Line 94: Line 133:
 ===== 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