mirror of
https://github.com/php/php-src.git
synced 2024-09-23 02:47:26 +00:00
0e60b812c0
The qa.php.net currently includes nice collection of information about tests and how to run them. Instead of maintaining two locations of this information, this patch removes the README.TESTING from the php-src repo. Patch for qa.php.net has been sent separately to that repo.
194 lines
7.9 KiB
Plaintext
194 lines
7.9 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 #winphp-dev 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://php.net/mailing-lists.php.
|
|
|
|
Information on PHP internal C functions is at
|
|
http://php.net/internals, though this is considered incomplete.
|
|
Various external resources can be found on the web. See
|
|
https://wiki.php.net/internals for some references. A standard
|
|
printed reference is the book "Extending and Embedding PHP" by Sara
|
|
Golemon.
|
|
|
|
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/.
|
|
|
|
If you are not using GitHub, attach your patch to a PHP bug and
|
|
consider sending a notification email about the change to
|
|
internals@lists.php.net. If the bug is for an extension, 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.
|
|
|
|
|
|
|
|
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://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 https://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!
|