1Submitting Enhancements and Patches to PHP 2========================================== 3 4This document describes how to submit an enhancement or patch for PHP. 5It's easy! 6 7You don't need any login accounts or special access to download, 8build, debug and begin submitting PHP or PECL code, tests or 9documentation. Once you've followed this README and had several 10patches accepted, commit privileges are often quickly granted. 11 12An excellent article to read first is: 13http://phpadvent.org/2008/less-whining-more-coding-by-elizabeth-smith 14 15 16Online Forums 17------------- 18There are several IRC channels where PHP developers are often 19available to discuss questions. They include #php.pecl and #php.doc 20on the EFNet network and #winphp-dev on FreeNode. 21 22 23PHP Patches 24----------- 25If you are fixing broken functionality in PHP C source code first 26create a bug or identify an existing bug at http://bugs.php.net/. A 27bug can be used to track the patch progress and prevent your changes 28getting lost in the PHP mail archives. 29 30If your change is large then create a Request For Comment (RFC) page 31on http://wiki.php.net/rfc, discuss it with the extension maintainer, 32and discuss it on the development mail list internals@lists.php.net. 33RFC Wiki accounts can be requested on 34http://wiki.php.net/start?do=register. PHP extension maintainers can 35be found in the EXTENSIONS file in the PHP source. Mail list 36subscription is explained on http://php.net/mailing-lists.php. 37 38Information on PHP internal C functions is at 39http://php.net/internals, though this is considered incomplete. 40Various external resources can be found on the web. See 41https://wiki.php.net/internals for some references. A standard 42printed reference is the book "Extending and Embedding PHP" by Sara 43Golemon. 44 45The preferred way to propose PHP patch is sending pull request from 46GitHub: https://github.com/php/php-src 47 48Fork the official PHP repository and send a pull request. A 49notification will be sent to the pull request mailing list. Sending a 50note to PHP Internals list (internals@lists.php.net) may help getting 51more feedback and quicker turnaround. You can also add pull requests 52to bug reports at http://bugs.php.net/. 53 54If you are not using GitHub, attach your patch to a PHP bug and 55consider sending a notification email about the change to 56internals@lists.php.net. If the bug is for an extension, also CC the 57extension maintainer. Explain what has been changed by your patch. 58Test scripts should be included. 59 60Please make the mail subject prefix "[PATCH]". If attaching a patch, 61ensure it has a file extension of ".txt". This is because only MIME 62attachments of type 'text/*' are accepted. 63 64 65 66PHP Documentation Patches 67------------------------- 68If you are fixing incorrect PHP documentation first create a bug or 69identify an existing bug at http://bugs.php.net/. A bug can be used 70to track the patch progress and prevent your changes getting lost in 71the PHP mail archives. 72 73If your change is large, then first discuss it with the mail list 74phpdoc@lists.php.net. Subscription is explained on 75http://php.net/mailing-lists.php. 76 77Information on contributing to PHP documentation is at 78http://php.net/dochowto and http://wiki.php.net/doc/howto 79 80Attach the patch to the PHP bug and consider sending a notification 81email about the change to phpdoc@lists.php.net. Explain what has been 82fixed/added/changed by your patch. 83 84Please make the mail subject prefix "[PATCH]". Include the bug id(s) 85which can be closed by your patch. If attaching a patch, ensure it 86has a file extension of ".txt". This is because only MIME attachments 87of type 'text/*' are accepted. 88 89 90PECL Extension Patches: http://pecl.php.net/ 91-------------------------------------------- 92If you are fixing broken functionality in a PECL extension then create 93a bug or identify an existing bug at http://bugs.php.net/. A bug 94can be used to track the patch progress and prevent your changes 95getting lost in the PHP mail archives. 96 97If your change is large then create a Request For Comment (RFC) page 98on http://wiki.php.net/rfc, discuss it with the extension maintainer, 99and discuss it on the development mail list pecl-dev@lists.php.net. 100PECL mail list subscription is explained on 101http://pecl.php.net/support.php. RFC Wiki accounts can be requested 102on http://wiki.php.net/start?do=register 103 104Information on PHP internal C functions is at 105http://www.php.net/internals, though this is considered incomplete. 106Various external resources can be found on the web. A standard 107printed reference is the book "Extending and Embedding PHP" by Sara 108Golemon. 109 110Update any open bugs and add a link to the source of your patch. Send 111the patch or pointer to the bug to pecl-dev@lists.php.net. Also CC 112the extension maintainer. Explain what has been changed by your 113patch. Test scripts should be included. 114 115Please make the mail subject prefix "[PATCH] ...". Include the patch 116as an attachment with a file extension of ".txt". This is because 117only MIME attachments of type 'text/*' are accepted. 118 119 120PEAR Package Patches: http://pear.php.net/ 121------------------------------------------ 122Information on contributing to PEAR is available at 123http://pear.php.net/manual/en/developers-newmaint.php and 124http://pear.php.net/manual/en/guide-developers.php 125 126 127How to create your PHP, PHP Documentation or PECL patch 128------------------------------------------------------- 129PHP and most PECL packages use Git for revision control. Some PECL 130packages use Subversion (SVN) Read http://www.php.net/git.php for help 131on using Git to get and build PHP source code. We recommend to look 132at our workflow on https://wiki.php.net/vcs/gitworkflow and our FAQ 133https://wiki.php.net/vcs/gitfaq. 134 135Generally we ask that bug fix patches work on the current stable PHP 136development branches and on "master". New PHP features only need to 137work on "master". 138 139Read CODING_STANDARDS before you start working. 140 141After modifying the source see README.TESTING and 142http://qa.php.net/write-test.php for how to test. Submitting test 143scripts helps us to understand what functionality has changed. It is 144important for the stability and maintainability of PHP that tests are 145comprehensive. 146 147After testing is finished, create a patch file using the command: 148 149 git diff > your_patch.txt 150 151For ease of review and later troubleshooting, submit individual 152patches for each bug or feature. 153 154 155Checklist for submitting your PHP or PECL code patch 156---------------------------------------------------- 157 - Update git source just before running your final 'diff' and 158 before testing. 159 - Add in-line comments and/or have external documentation ready. 160 Use only "/* */" style comments, not "//". 161 - Create test scripts for use with "make test". 162 - Run "make test" to check your patch doesn't break other features. 163 - Rebuild PHP with --enable-debug (which will show some kinds of 164 memory errors) and check the PHP and web server error logs after 165 running your PHP tests. 166 - Rebuild PHP with --enable-maintainer-zts to check your patch 167 compiles on multi-threaded web servers. 168 - Review the patch once more just before submitting it. 169 170 171What happens after submitting your PHP, PHP Documentation or PECL patch 172----------------------------------------------------------------------- 173If your patch is easy to review and obviously has no side-effects, 174it might be committed relatively quickly. 175 176Because PHP is a volunteer-driven effort more complex patches will 177require patience on your side. If you do not receive feedback in a 178few days, consider resubmitting the patch. Before doing this think 179about these questions: 180 181 - Did I send the patch to the right mail list? 182 - Did I review the mail list archives to see if these kind of 183 changes had been discussed before? 184 - Did I explain my patch clearly? 185 - Is my patch too hard to review? Because of what factors? 186 187 188What happens when your PHP or PECL patch is applied 189--------------------------------------------------- 190Your name will likely be included in the Git commit log. If your 191patch affects end users, a brief description and your name might be 192added to the NEWS file. 193 194Thank you for patching PHP! 195
