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