mirror of
https://github.com/php/php-src.git
synced 2024-09-23 02:47:26 +00:00
137 lines
5.0 KiB
Plaintext
137 lines
5.0 KiB
Plaintext
Submitting Patches to PHP
|
|
=========================
|
|
|
|
This document describes how to submit a patch for PHP. Creating a
|
|
patch for PHP is 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.
|
|
|
|
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/). Mail list subscription is
|
|
explained on http://www.php.net/mailing-lists.php.
|
|
|
|
If a PHP or PECL patch affects user-functionality or makes significant
|
|
internal changes then create a simple RFC 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
|
|
|
|
There are several IRC channels where PHP developers are often
|
|
available to discuss questions. They include #php.pecl on the EFNet
|
|
network and #php-dev-win on FreeNode.
|
|
|
|
|
|
How to create your patch
|
|
------------------------
|
|
PHP uses 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
|
|
http://svnbook.red-bean.com.
|
|
|
|
Generally we ask that patches work on the current stable PHP
|
|
development branch and 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
|
|
important for the stability and maintainability of PHP that tests are
|
|
comprehensive.
|
|
|
|
After testing is finished, create a patch file using the command:
|
|
|
|
svn diff > your_patch.txt
|
|
|
|
For ease of review and later troubleshooting, submit individual
|
|
patches for each bug or feature.
|
|
|
|
|
|
Checklist for submitting your patch
|
|
-----------------------------------
|
|
- Update SVN source just before running your final 'diff' and
|
|
before testing.
|
|
- 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.
|
|
- 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
|
|
|
|
The mail can be CC'd to the extension maintainer (see EXTENSIONS).
|
|
|
|
Please make the subject prefix "[PATCH]".
|
|
|
|
Include the patch as an attachment. Note: only MIME attachments of
|
|
type 'text/*' are accepted. The easiest way to accomplish this is to
|
|
make the file extension '.txt'.
|
|
|
|
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
|
|
----------------------------------------
|
|
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:
|
|
|
|
- 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?
|
|
|
|
|
|
What happens when your patch is applied
|
|
---------------------------------------
|
|
Your name will be included together with your email address 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!
|