release/src/router/php/README.SUBMITTING_PATCH

   1 Submitting Enhancements and Patches to PHP
   2 ==========================================
   3
   4 This document describes how to submit an enhancement or patch for PHP.
   5 It's easy!
   6
   7 You don't need any login accounts or special access to download,
   8 build, debug and begin submitting PHP, PECL or PEAR code, tests or
   9 documentation.  Once you've followed this README and had several
  10 patches accepted, commit privileges are often quickly granted.
  11
  12 An excellent article to read first is:
  13 http://phpadvent.org/2008/less-whining-more-coding-by-elizabeth-smith
  14
  15
  16 Online Forums
  17 -------------
  18 There are several IRC channels where PHP developers are often
  19 available to discuss questions.  They include #php.pecl, #php.doc and
  20 #pear on the EFNet network and #php-dev-win on FreeNode.
  21
  22
  23 PHP Patches
  24 -----------
  25 If you are fixing broken functionality in PHP C source code first
  26 create a bug or identify an existing bug at http://bugs.php.net/.  A
  27 bug can be used to track the patch progress and prevent your changes
  28 getting lost in the PHP mail archives.
  29
  30 If your change is large then create a Request For Comment (RFC) page
  31 on http://wiki.php.net/rfc, discuss it with the extension maintainer,
  32 and discuss it on the development mail list internals@lists.php.net.
  33 RFC Wiki accounts can be requested on
  34 http://wiki.php.net/start?do=register.  PHP extension maintainers can
  35 be found in the EXTENSIONS file in the PHP source.  Mail list
  36 subscription is explained on http://www.php.net/mailing-lists.php.
  37
  38 Information on PHP internal C functions is at
  39 http://www.php.net/internals, though this is considered incomplete.
  40 Various external resources can be found on the web.  A standard
  41 printed reference is the book "Extending and Embedding PHP" by Sara
  42 Golemon.
  43
  44 Attach the patch to the PHP bug and consider sending a notification
  45 email about the change to internals@lists.php.net.  Also CC the
  46 extension maintainer.  Explain what has been changed by your patch.
  47 Test scripts should be included.
  48
  49 Please make the mail subject prefix "[PATCH]".  If attaching a patch,
  50 ensure it has a file extension of ".txt".  This is because only MIME
  51 attachments of type 'text/*' are accepted.
  52
  53
  54 PHP Documentation Patches
  55 -------------------------
  56 If you are fixing incorrect PHP documentation first create a bug or
  57 identify an existing bug at http://bugs.php.net/.  A bug can be used
  58 to track the patch progress and prevent your changes getting lost in
  59 the PHP mail archives.
  60
  61 If your change is large, then first discuss it with the mail list
  62 phpdoc@lists.php.net.  Subscription is explained on
  63 http://www.php.net/mailing-lists.php.
  64
  65 Information on contributing to PHP documentation is at
  66 http://php.net/dochowto and http://wiki.php.net/doc/howto
  67
  68 Attach the patch to the PHP bug and consider sending a notification
  69 email about the change to phpdoc@lists.php.net.  Explain what has been
  70 fixed/added/changed by your patch.
  71
  72 Please make the mail subject prefix "[PATCH]".  Include the bug id(s)
  73 which can be closed by your patch.  If attaching a patch, ensure it
  74 has a file extension of ".txt".  This is because only MIME attachments
  75 of type 'text/*' are accepted.
  76
  77
  78 PECL Extension Patches: http://pecl.php.net/
  79 --------------------------------------------
  80 If you are fixing broken functionality in a PECL extension then create
  81 a bug or identify an existing bug at http://pecl.php.net/bugs/.  A bug
  82 can be used to track the patch progress and prevent your changes
  83 getting lost in the PHP mail archives.
  84
  85 If your change is large then create a Request For Comment (RFC) page
  86 on http://wiki.php.net/rfc, discuss it with the extension maintainer,
  87 and discuss it on the development mail list pecl-dev@lists.php.net.
  88 PECL mail list subscription is explained on
  89 http://pecl.php.net/support.php.  RFC Wiki accounts can be requested
  90 on http://wiki.php.net/start?do=register
  91
  92 Information on PHP internal C functions is at
  93 http://www.php.net/internals, though this is considered incomplete.
  94 Various external resources can be found on the web.  A standard
  95 printed reference is the book "Extending and Embedding PHP" by Sara
  96 Golemon.
  97
  98 Update any open bugs and add a link to the source of your patch.  Send
  99 the patch or pointer to the bug to pecl-dev@lists.php.net.  Also CC
 100 the extension maintainer.  Explain what has been changed by your
 101 patch.  Test scripts should be included.
 102
 103 Please make the mail subject prefix "[PATCH] ...".  Include the patch
 104 as an attachment with a file extension of ".txt".  This is because
 105 only MIME attachments of type 'text/*' are accepted.
 106
 107
 108 PEAR Package Patches: http://pear.php.net/
 109 ------------------------------------------
 110 Information on contributing to PEAR is available at
 111 http://pear.php.net/manual/en/developers-newmaint.php and
 112 http://pear.php.net/manual/en/guide-developers.php
 113
 114
 115 How to create your PHP, PHP Documentation or PECL patch
 116 -------------------------------------------------------
 117 PHP and PECL use Subversion (SVN) for revision control.  Read
 118 http://www.php.net/svn.php for help on using SVN to get and build PHP
 119 source code.  We recommend using a Sparse Directory checkout described
 120 in http://wiki.php.net/vcs/svnfaq.  If you are new to SVN, read
 121 http://svnbook.red-bean.com.
 122
 123 Generally we ask that bug fix patches work on the current stable PHP
 124 development branches and on "trunk".  New PHP features only need to
 125 work on "trunk".
 126
 127 Read CODING_STANDARDS before you start working.
 128
 129 After modifying the source see README.TESTING and
 130 http://qa.php.net/write-test.php for how to test.  Submitting test
 131 scripts helps us to understand what functionality has changed.  It is
 132 important for the stability and maintainability of PHP that tests are
 133 comprehensive.
 134
 135 After testing is finished, create a patch file using the command:
 136
 137   svn diff > your_patch.txt
 138
 139 For ease of review and later troubleshooting, submit individual
 140 patches for each bug or feature.
 141
 142
 143 Checklist 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
 159 What happens after submitting your PHP, PHP Documentation or PECL patch
 160 -----------------------------------------------------------------------
 161 If your patch is easy to review and obviously has no side-effects,
 162 it might be committed relatively quickly.
 163
 164 Because PHP is a volunteer-driven effort more complex patches will
 165 require patience on your side.  If you do not receive feedback in a
 166 few days, consider resubmitting the patch.  Before doing this think
 167 about 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
 176 What happens when your PHP or PECL patch is applied
 177 ---------------------------------------------------
 178 Your name will likely be included in the SVN commit log.  If your
 179 patch affects end users, a brief description and your name might be
 180 added to the NEWS file.
 181
 182 Thank you for patching PHP!