diff options
author | Christopher Jones <sixd@php.net> | 2010-05-11 18:25:44 +0000 |
---|---|---|
committer | Christopher Jones <sixd@php.net> | 2010-05-11 18:25:44 +0000 |
commit | 8b1dc1b6eb02cb047918ad0ab70d3508762dd789 (patch) | |
tree | 63605eabd1b6b994dc966c71ef1e33f2a1f2225d /README.SUBMITTING_PATCH | |
parent | cfce0a982897ab2f20807eb9ce1616a1d44f51e6 (diff) | |
download | php-git-8b1dc1b6eb02cb047918ad0ab70d3508762dd789.tar.gz |
Restructure into PHP/PECL/PEAR component areas (at the expense of duplication)
Diffstat (limited to 'README.SUBMITTING_PATCH')
-rw-r--r-- | README.SUBMITTING_PATCH | 224 |
1 files changed, 127 insertions, 97 deletions
diff --git a/README.SUBMITTING_PATCH b/README.SUBMITTING_PATCH index e20eb945de..63b7156f10 100644 --- a/README.SUBMITTING_PATCH +++ b/README.SUBMITTING_PATCH @@ -1,74 +1,134 @@ -Submitting Patches to PHP -========================= +Submitting Enhancements and Patches to PHP +========================================== -This document describes how to submit a patch for PHP. Creating a -patch for PHP is easy! +This document describes how to submit an enhancement or patch for PHP. +It's easy! You don't need any login accounts or special access to download, -build, debug and begin submitting PHP code, tests or documentation for -inclusion in PHP. Once you've followed this README and had several -patches accepted, PHP commit privileges are often quickly granted. +build, debug and begin submitting PHP, PECL or PEAR code, tests or +documentation. Once you've followed this README and had several +patches accepted, commit privileges are often quickly granted. An excellent article to read first is: http://phpadvent.org/2008/less-whining-more-coding-by-elizabeth-smith -Prework -------- -If you are fixing broken functionality then create a bug or identify -an existing bug at http://bugs.php.net/. This can be used to track -the patch progress and prevent your changes getting lost in the PHP -mail archives. - -If your code change is large, then first discuss it with the extension -maintainer and/or a development mail list. Extension maintainers can -be found in the EXTENSIONS file in the PHP source. Use the -internals@lists.php.net mail list to discuss changes to the base PHP -code. Use pecl-dev@lists.php.net for changes to code that is only -available from PECL (http://pecl.php.net/). Use pear-dev@lists.php.net -for PEAR modules (http://pear.php.net/). Use phpdoc@lists.php.net for -PHP documentation questions. Mail list subscription is explained on -http://www.php.net/mailing-lists.php. +Online Forums +------------- +There are several IRC channels where PHP developers are often +available to discuss questions. They include #php.pecl, #php.doc and +#pear on the EFNet network and #php-dev-win on FreeNode. + + +PHP Patches +----------- +If you are fixing broken functionality in PHP C source code first +create a bug or identify an existing bug at http://bugs.php.net/. A +bug can be used to track the patch progress and prevent your changes +getting lost in the PHP mail archives. + +If your change is large then create a Request For Comment (RFC) page +on http://wiki.php.net/rfc, discuss it with the extension maintainer, +and discuss it on the development mail list internals@lists.php.net. +RFC Wiki accounts can be requested on +http://wiki.php.net/start?do=register. PHP extension maintainers can +be found in the EXTENSIONS file in the PHP source. Mail list +subscription is explained on http://www.php.net/mailing-lists.php. + +Information on PHP internal C functions is at +http://www.php.net/internals, though this is considered incomplete. +Various external resources can be found on the web. A standard +printed reference is the book "Extending and Embedding PHP" by Sara +Golemon. -If a PHP or PECL patch affects user functionality or makes significant -internal changes then create a simple Request For Comment (RFC) page -on http://wiki.php.net/rfc before starting discussion. This RFC can be -used for initial discussion and later for documentation. Wiki accounts -can be requested on http://wiki.php.net/start?do=register +Attach the patch to the PHP bug and consider sending a notification +email about the change to internals@lists.php.net. Also CC the +extension maintainer. Explain what has been changed by your patch. +Test scripts should be included. -Online information on PHP internal C functions is at -http://www.php.net/internals, though this is considered -incomplete. Various external resources can be found on the web. A -standard reference is the book "Extending and Embedding PHP" by Sara -Golemon. +Please make the mail subject prefix "[PATCH]". If attaching a patch, +ensure it has a file extension of ".txt". This is because only MIME +attachments of type 'text/*' are accepted. -Information on contributing to PEAR is available at -http://pear.php.net/manual/en/guide-developers.php + +PHP Documentation Patches +------------------------- +If you are fixing incorrect PHP documentation first create a bug or +identify an existing bug at http://bugs.php.net/. A bug can be used +to track the patch progress and prevent your changes getting lost in +the PHP mail archives. + +If your change is large, then first discuss it with the mail list +phpdoc@lists.php.net. Subscription is explained on +http://www.php.net/mailing-lists.php. Information on contributing to PHP documentation is at http://php.net/dochowto and http://wiki.php.net/doc/howto -There are several IRC channels where PHP developers are often -available to discuss questions. They include #php.pecl and #php.doc -on the EFNet network and #php-dev-win on FreeNode. +Attach the patch to the PHP bug and consider sending a notification +email about the change to phpdoc@lists.php.net. Explain what has been +fixed/added/changed by your patch. + +Please make the mail subject prefix "[PATCH]". Include the bug id(s) +which can be closed by your patch. If attaching a patch, ensure it +has a file extension of ".txt". This is because only MIME attachments +of type 'text/*' are accepted. + + +PECL Extension Patches: http://pecl.php.net/ +-------------------------------------------- +If you are fixing broken functionality in a PECL extension then create +a bug or identify an existing bug at http://pecl.php.net/bugs/. A bug +can be used to track the patch progress and prevent your changes +getting lost in the PHP mail archives. + +If your change is large then create a Request For Comment (RFC) page +on http://wiki.php.net/rfc, discuss it with the extension maintainer, +and discuss it on the development mail list pecl-dev@lists.php.net. +PECL mail list subscription is explained on +http://pecl.php.net/support.php. RFC Wiki accounts can be requested +on http://wiki.php.net/start?do=register + +Information on PHP internal C functions is at +http://www.php.net/internals, though this is considered incomplete. +Various external resources can be found on the web. A standard +printed reference is the book "Extending and Embedding PHP" by Sara +Golemon. + +Update any open bugs and add a link to the source of your patch. Send +the patch or pointer to the bug to pecl-dev@lists.php.net. Also CC +the extension maintainer. Explain what has been changed by your +patch. Test scripts should be included. + +Please make the mail subject prefix "[PATCH] ...". Include the patch +as an attachment with a file extension of ".txt". This is because +only MIME attachments of type 'text/*' are accepted. + + +PEAR Package Patches: http://pear.php.net/ +------------------------------------------ +Information on contributing to PEAR is available at +http://pear.php.net/manual/en/developers-newmaint.php and +http://pear.php.net/manual/en/guide-developers.php -How to create your patch ------------------------- -PHP uses Subversion (SVN) for revision control. Read +How to create your PHP, PHP Documentation or PECL patch +------------------------------------------------------- +PHP and PECL use Subversion (SVN) for revision control. Read http://www.php.net/svn.php for help on using SVN to get and build PHP -source code. We recommend using a Sparse Directory checkout described -in http://wiki.php.net/vcs/svnfaq. If you are new to SVN, read +source code. We recommend using a Sparse Directory checkout described +in http://wiki.php.net/vcs/svnfaq. If you are new to SVN, read http://svnbook.red-bean.com. -Generally we ask that patches work on the current stable PHP -development branch and on "trunk". +Generally we ask that bug fix patches work on the current stable PHP +development branches and on "trunk". New PHP features only need to +work on "trunk". Read CODING_STANDARDS before you start working. After modifying the source see README.TESTING and -http://qa.php.net/write-test.php for how to test. Submitting test -scripts helps us to understand what functionality has changed. It is +http://qa.php.net/write-test.php for how to test. Submitting test +scripts helps us to understand what functionality has changed. It is important for the stability and maintainability of PHP that tests are comprehensive. @@ -80,73 +140,43 @@ For ease of review and later troubleshooting, submit individual patches for each bug or feature. -Checklist for submitting your patch ------------------------------------ +Checklist for submitting your PHP or PECL code patch +---------------------------------------------------- - Update SVN source just before running your final 'diff' and before testing. + - Add in-line comments and/or have external documentation ready. + Use only "/* */" style comments, not "//". + - Create test scripts for use with "make test". - Run "make test" to check your patch doesn't break other features. - Rebuild PHP with --enable-debug (which will show some kinds of memory errors) and check the PHP and web server error logs after - running the PHP tests. - - Rebuild PHP with --enable-maintainer-zts to check your patch compiles - on multi-threaded web servers. - - Create test scripts for use with "make test". - - Add in-line comments and/or have external documentation ready. + running your PHP tests. + - Rebuild PHP with --enable-maintainer-zts to check your patch + compiles on multi-threaded web servers. - Review the patch once more just before submitting it. -Where to send your patch ------------------------- -If you are patching PHP C source then email the patch to -internals@lists.php.net - -If you patching a PECL extension then send the patch to -pecl-dev@lists.php.net - -If you are patching PEAR then send the patch to -pear-dev@lists.php.net - -If you are patching PHP's documentation then send the patch to -phpdoc@lists.php.net - -The mail can be CC'd to the extension maintainer (see EXTENSIONS). - -Please make the subject prefix "[PATCH]", for example "[PATCH] Fix -return value of all array functions" - -Include the patch as an attachment with a file extension of ".txt". -This is because only MIME attachments of type 'text/*' are accepted. - -Explain what has been fixed/added/changed by your patch. Test scripts -should be included in the email. - -Include the bug id(s) which can be closed by your patch. - -Finally, update any open bugs and add a link to the source of your -patch. - - -What happens after you submit your patch ----------------------------------------- +What happens after submitting your PHP, PHP Documentation or PECL patch +----------------------------------------------------------------------- If your patch is easy to review and obviously has no side-effects, it might be committed relatively quickly. Because PHP is a volunteer-driven effort more complex patches will -require patience on your side. If you do not receive feedback in a few -days, consider resubmitting the patch. Before doing this think about -these questions: +require patience on your side. If you do not receive feedback in a +few days, consider resubmitting the patch. Before doing this think +about these questions: + - Did I send the patch to the right mail list? - Did I review the mail list archives to see if these kind of changes had been discussed before? - Did I explain my patch clearly? - - Is my patch too hard to review? Because of which factors? - - Are there any unwanted white space changes? + - Is my patch too hard to review? Because of what factors? -What happens when your patch is applied ---------------------------------------- -Your name will be included in the SVN commit log. If your patch -affects end users, a brief description and your name might be added to -the NEWS file. +What happens when your PHP or PECL patch is applied +--------------------------------------------------- +Your name will likely be included in the SVN commit log. If your +patch affects end users, a brief description and your name might be +added to the NEWS file. Thank you for patching PHP! |