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