mirror of
https://github.com/php/php-src.git
synced 2024-11-23 18:04:36 +08:00
223a62d69e
* PHP-5.5: Fix English and improve by Stas. Thanks :) Update source docs Revert "Update source docs" Update source docs Conflicts: README.EXTENSIONS
194 lines
7.8 KiB
Plaintext
194 lines
7.8 KiB
Plaintext
Submitting Enhancements and Patches to PHP
|
|
==========================================
|
|
|
|
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 or PECL 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
|
|
|
|
|
|
Online Forums
|
|
-------------
|
|
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.
|
|
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
The preferred way to propose PHP patch is sending pull request from
|
|
github.
|
|
|
|
https://github.com/php/php-src
|
|
|
|
Fork the official PHP repository and send a pull request. A
|
|
notification will be sent to the pull request mailing list. Sending a
|
|
note to PHP Internals list (internals@lists.php.net) may help getting
|
|
more feedback and quicker turnaround. You can also add pull requests
|
|
to bug reports at http://bugs.php.net/.
|
|
|
|
|
|
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
|
|
|
|
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://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 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 PHP, PHP Documentation or PECL patch
|
|
-------------------------------------------------------
|
|
PHP and most PECL packages use Git for revision control. Some PECL
|
|
packages use Subversion (SVN) Read http://www.php.net/git.php for help
|
|
on using Git to get and build PHP source code. We recommend to look
|
|
at our workflow on https://wiki.php.net/vcs/gitworkflow and our FAQ
|
|
https://wiki.php.net/vcs/gitfaq.
|
|
|
|
Generally we ask that bug fix patches work on the current stable PHP
|
|
development branches and on "master". New PHP features only need to
|
|
work on "master".
|
|
|
|
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:
|
|
|
|
git diff > your_patch.txt
|
|
|
|
For ease of review and later troubleshooting, submit individual
|
|
patches for each bug or feature.
|
|
|
|
|
|
Checklist for submitting your PHP or PECL code patch
|
|
----------------------------------------------------
|
|
- Update git 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 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.
|
|
|
|
|
|
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:
|
|
|
|
- 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 what factors?
|
|
|
|
|
|
What happens when your PHP or PECL patch is applied
|
|
---------------------------------------------------
|
|
Your name will likely be included in the Git 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!
|