Return to README.SUBMITTING_PATCH CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php

php 5.4.29

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